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1. Document IC Library 


di__intro 


NAME 
di__intro - introductory explanation of document interchange functions 
DESCRIPTION 


The DoclC interface is a C-based programming tool that allows a person to create a new VP document or 
read an existing one. Also, new data may be added directly to the end of an existing VP document. The 
contents of an existing VP document may not be changed or deleted. But, through the use of an 
intermediary file, the contents of an existing VP file may be read up to a certain point and inserted within 
the intermediary file, the new data inserted, and the remainder of the VP document read. The same basic 
approach may be used to delete select data from a document: An existing VP document may be read up toa 
certain point and the information placed in an intermediary file. The undesired data may be skipped, and 
the remaining data is read and placed in the intermediary file. 


The DoclC interface provides functions that may be used to create or read any of the basic VP document 
structures, such as text; fields; headings and footings; or frames of varying types. 


Data is placed in a frame by the calling the DociC interface functions that correspond to that particular 
type of frame. Currently, there are only two IC interfaces available that may be used to manipulate the 
contents of a frame. They are GraphicsiC and TablelC. GraphicsiC functions are used to create or read 
graphics frames and button frames. TablelC functions are used to create or read tables. 


Document Creation 


A VP document is initially created by calling either di start() ordi startap(). Both of these two functions 
set up data structures for the document being created and return a handle to the newly created document. 
This handle is an identifier that is passed as an argument to other DoclIC interchange functions as the 
means of identifying the document being manipulated. 


The next step in creating a document is to add information to the document by calls to various di ap*() 
functions. These functions are di apaframe(), di apbreak(), di apchar(), di apfield(), di apfntile(), 
di apindex(),di apnewpara(),di appfc(),di aptext(),di aptofillin(),di apfstyleQ,di appstyle(), and 
di__aptotxtink(). — . — _ a = 


With regards to di apaframe(), the function used to anchor a frame to an object in a document, the user 
typically calls various GraphicsIC or TablelC functions to create the contents of a frame, and then calls 
di apaframe() to append that frame and its contents to the document. With regards to di starttext(), the 
user calls di apaframe() first and thencallsdi starttext() to obtain a text handle. The handle returned by 
a call to di _apafra me() is then passed as an argument to di__starttext(). 


di_apfield(), di __apindex() anddi appfc() all have return values. This allows the user to recursively call 
di ap*() functions to add text and formatting information to fields, index, or PFC headers. 
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When all the desired data has been added to a document, call di__finish() to obtain a temporary reference, 
or handle. Then call the Desktop Library function dsktp _move() so that the resulting file may be placed 
on the VP desktop. 


Document Enumeration 


To enumerate the contents of an existing VP document, the first step is a call to dsktp getdocref(). 
dsktp getdocref() will return a handle for the specified document. Once the handle has been obtained, the 
contents may be manipulated. Next call di open(). This function opens the specified document and 
returns doc, a handle for the document. Next, pass the handle and a di enumprocs structure as 
arguments in a call to di enumerate(). The di enumprocs structure consists of a set of call-back 
procedures, where there is one call-back procedure for each of the corresponding object types that exist in 
the document. Objects, in this case, are defined as anchored frames, break characters, field, footnotes, 
indexes, new paragraphs, page format characters, or text. 


The di enumerate() function inspects a document from beginning to end. As different types of objects are 
encountered, this function calls the appropriate call-back procedure to process each particular type of 
object. Each call-back procedure returns a Boolean value. A value of TRUE terminates the enumeration. If 
TRUE is never returned, the enumeration continues to the end of the document. 


Enumeration proceeds according to the “main flow” of text within a document. Main flow is considered to 
be the sequence of text that contains page format characters and frame anchor characters. This means 
that the call-back procedure, di aframeproc(), will be called not when the frame itself is reached, but 
rather when the frame’s anchor character is reached. 


When the enumeration is complete, di__close() should be called to free all associated data structures and 
close any open file handles to the document. 


Note that document creation and enumeration are totally separate activities and the functions and 
handles associated with one should not be used with the other. Enumeration is a read-only operation; no 
editing should be attempted while it is in progress. Likewise, enumeration should not be attempted when 
creating a document. 


Data types 


1-2 


The basic data structure of the DoclIC interface is di_tcont (text container).di tcont may be defined as any 
object that can contain text. A di tcont can be a caption, document, field, footing, heading, index, 
numbering, or text. 


d i_tcont is defined in DocIC.h as follows: 


typedef struct { 
di tcont type type; 
union{ 
di caption caption; 
di doc doc; 
di field field; 
di footing footing; 
di heading heading; 
di index index; 
di numbering — numbering; 
di text text; 
dhe 
_}di_tcont; 


where, all elements inside the union h are unsigned integers. 
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di tcont must contain at least one new paragraph character, since the paragraph properties of text are 
inherited from the preceding new paragraph character. The implementation of the DocIC interface 
automatically inserts the initial new paragraph characters as required. Therefore, it is always safe to 
assume they already exist. (You are free to append new paragraph characters, regardless. The 
implementation ensures that duplicate new paragraph characters do not appear in the document. The new 
paragraph characters inserted by the user have precedence over those inserted by the system. ) 


di ins isa handle to specific instances of objects within a document. Many objects in a document may be 
uniquely identified and accessed viadi_ins. In general, instances form the bridge between DoclC interfaces 
and the interfaces that are used specifically to manipulate the contents of frames, such as GraphicsIC and 
TablelC: DocIC interfaces provide an instance which may be passed to other Interchange interfaces. No 
object in any document may be accessed via di__insnil. 


Table of DocIC Interfaces 


The following table summarizes DoclC interfaces. 


Creatina 
Object 
Function 
Common 


Document di start 
di abort 

Text di aptext 

di reltext 


Anchored di starttext 
Text Frame di apaframe 


Readina 


Function 


di enumerate 


di open 
di close 


di textproc 
di reltext 


di aframeproc 
di _textforaframe 
di relcap 
di aframeproc 


~ Anchored di setfnprops 


Footnote di apaframe di fnpropsproc 
di fntile 


di relcap 


di getfnprops 


di fntileproc 


Other Anchored 
Frame 


di apaframe di aframeproc 





di_relcap 


Field di_ field 
di__relfield 

Index di apindex 
di_relindex 


Newpara di apnewpara 
di setpara 


di breakproc 


di fieldproc 
di_getfieldfromname | 
dp enumfrun 


di_indexproc 


di newparaproc 
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di__abort 


NAME 


di__abort - abort document creation 
SYNOPSIS 
#include “DociC.h” 
Int 
di_a bort(doc) 
di__doc *doc; 
DESCRIPTION 


The di__abort() function is used to terminate the document generation process and deallocate the storage 
resources allocated to the document being terminated. This function’s one argument is di__doc, the file 
handle returned by an earlier call todi__start()ordi__startap(). 


RETURN VALUE 


If the call is successful, 0 is returned, otherwise -1 is returned. The function getsigno() is used to get the 
reason for the failure. 


ERRORS 


di_a bort() will fail if one or more of the following is true: 


Doc BadParm One of the specified arguments is invalid. 
Doc IllegalHandle The specified handle is illegal. 


Doc TimeOut Inter-process communication has exceeded the maximum allowed time. 
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di__apaframe 


NAME 


di__apaframe - append anchored frame 
SYNOPSIS 


#include “DocIC.h” 
#include “DociCProps.h” 


int 
di apaframe(to, type, frame, cont, wtcap, wbcap, wicap, wrcap, font, trustsize, ret) 
~ di tcont *to; 
di aframetype type; 
dp frameprops *frame; 


di ins cont; /* di insnil */ 
dp bool wtcap; /* FALSE */ 

dp bool whcap; /* FALSE */ 

dp bool wicap; /* FALSE */ 

dp bool wrcap; /* FALSE */ 

dp fontprops *font; /* NULL */ 

dp bool trustsize; /* FALSE */ 
ret__apaframe *ret; /* Returned */ 

DESCRIPTION 


The di_apaframe() function is used to append an anchored frame to the text container specified by 
di__tcont. The resulting frame will be of a specific type and it will have specific format properties. 


to is a pointer of the type di tcont. It is a structure that defines the type of object contained within it and a 
handle to the object itself. di tcont consists of a union of two members, type and h. The object type is 
defined by the member type. type is of the type di tcont type. It is an enumerated variable that may be 
set to one of the following values: _ 7 


TC CAPTION 

TC DOC 

TC FIELD 

TC FOOTING 
TC HEADING 
TC INDEX 

TC NUMBERING 
TC TEXT 


The h member of di__tcontis an opaque variable that is to contain a handle returned by a previous call to a 
related handle generating function. It may contain one the following types: 


di caption 

di doc 

di field 

di footing 

di heading 

di index 

di numbering 
di text 
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The user specifies the handle type and its contents. In the case of di__apaframe(), the type is to be set to 
TC DOCand the handle is tocontainthe return value ofeitherdi start()ordi startap(). Appendingan 
anchored frame to a caption, text, heading, footing, or numbering container is not allowed. 


The type argument is of the type di__aframetype. It is an enumerated variable that specifies the type of 
anchored frame to be appended to the document container. It may be set to one of the following values: 


AF CUSP Cusp Button 
AF GRAPH Graphics 
AF TABLE Table 

AF TEXT Text 

AF FNOTE Footnote 
AF OTHER Other type 


The frame argument isa pointer of the typedp frameprops, a structure containing variables that control 
the appearance, dimensions, and page numbering of the frame in question. 


The cont argument is the contents to be inserted in the frame. Currently, only interfaces that support the 
creation of graphic, table, text, and button frames are available. 


The w*cap argument specifies the captions the frame should have. 


font specifies the font properties of the frame anchor. Changing the font properties of the anchor does not 
affect the appearance of the anchor, but it does affect the default properties that succeeding characters will 
inherit. 


trustsize is a Boolean value that controls the dimensions of the frame. If trustsize is set to TRUE, the frame 
size specified in frame will be used without modification. If set to FALSE, the frame size specified in frame 
will be ignored and the frame will be adjusted to fit the existing frame. This argument may only be set to 
TRUE when manipulating anchored table frames. 


The return information is set into the structure ret apaframe. It contains the following members: 


di__ins frame; 

di caption tcap; 
di caption bcap; 
di caption Icap; 
di _caption rcap; 


The return information contains handles to the frame and its captions. The caption handles will be non- 
NULL only if the user specifies TRUE for the corresponding w*cap parameter. The user must later release 
each valid caption handle with calls todi__relcap(). 


frame is a pointer of type ret __apafra me. The handle contained in ret__apaframe is passed as an argument 
incallstodi starttext()and gi setgframeprops(). It is not mandatory to call di __Starttext() after calling 
di__apafra me(). Failure tocalldi starttext() will only result in an empty text frame, except for the presence 
of one new paragraph character that has default paragraph and font properties. 


RETURN VALUE 


If the call is successful 0 is returned, otherwise -1 is returned. The function getsigno() is used to get the 
reason for the failure. 
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ERRORS 
di__apaframe() will fail if one or more of the following is true: | 


Doc_ContainerFull | No more room to append to this container. 

Doc DocumentFull No more room in the document. 

Doc ReadonlyDoc Document opened in ReadOnly mode. 

Doc OutOfDiskSpace Not enough disk space for the operation. 

Doc OutOfVM Not enough virtual memory for the operation. 

Doc ObjillegalinCont Attempted to add an object of an unsupported type to a container. 
Doc BadParm One of the specified arguments is invalid. 


Doc_IllegalHandile The specified handle is illegal. 


Doc TimeOut Inter-process communication has exceeded the maximum allowed time. 
Doc Unimpl This function is not supported. 
SEE ALSO 


di_relcap(),di__starttext(), gi__setgframeprops() 


ee 
ig 
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di__apbreak 


NAME 
di__apbreak - append break character 


SYNOPSIS 


#include “DociC.h” 
#include “DociCProps.h” 


int 
di apbreak(to, brprops, foprops) 
~ di tcont *to; 
dp breakprops *brprops; 
dp _fontprops *foprops; /* NULL */ 


DESCRIPTION 
The di _apbreak() function is used to append a page break character to the container specified by di_tcont. 


Refer to di__apaframe() for a description ofdi__tcont. Note that heading, footing and numbering containers 
may not be used. 


brprops are the properties of the break character. Refer to the DocICProps section of this manual and the 
VP reference manuals for more information regarding text frame properties. 


foprops are the font properties of the break character. The addition of these properties will not affect the 
appearance of the character itself, but will affect the properties that succeeding characters will inherit. 


RETURN VALUE 


If the call is successful 0 is returned, otherwise -1 is returned. The function getsigno() is used to get the 
reason for the failure. 


ERRORS 
di_a pbreak() will fail if one or more of the following is true: 


Doc ContainerFull There is no more room to append to this container. 
Doc DocumentFull No more room in the document. 
Doc_ ReadonlyDoc Document opened in ReadOnly mode. 


Doc OutOfDiskSpace Not enough disk space for the operation. 


Doc OutOfVM Not enough virtual memory for the operation. 

Doc ObjillegallnCont Attempted to add an object of an unsupported type to a container. 

Doc BadParm One of the specified arguments is invalid. 

Doc_IllegalHandle = The specified handle is illegal. 

Doc TimeOut Inter-process communication has exceeded the maximum allowed time. 
Doc _Unimpl This function is not supported. 
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di__apchar 


NAME 


di__apchar - append character 
SYNOPSIS 


#include “DociC.h” 
#include “DociCProps.h” 
#include "XString.h” 


int 
di__apchar(to, c, foprops, num) 
di tcont *to; 


XChar c; | 

dp fontprops *foprops; /* NULL */ 

unsigned num; PEE] 
DESCRIPTION 


The di__apchar() function is used to append one or more instances of the text character ¢ to the specified 
di_tcont. Refer to di_a paframe() for a description of di_tcont. 


The num argument specifies the number of times the character specified in ¢ will be appended to the text 
container. The foprops argument specifies the font properties of the character(s). 


RETURN VALUE 


If the call is successful 0 is returned, otherwise -1 is returned. The function getsigno() is used to get the 
reason for the failure. 


ERRORS 
di_a pchar() will fail if one or more of the following is true: 


Doc ContainerFull There is no more room to append to this container. 
Doc _ DocumentFull No more room in the document. 
Doc _ReadonlyDoc Document opened in ReadOnly mode. 
—Doc_OutOfDiskSpace Not enough disk space for the operation. 
Doc OutOfVM Not enough virtual memory for the operation. 
Doc ObjillegalinCont Attempted to add an object of an unsupported type to a container. 
Doc _BadParm One of the specified arguments is invalid. | 
Doc_IllegalHandle = The specified handle is illegal. 
Doc _ TimeOut Inter-process communication has exceeded the maximum allowed time. 


Doc _Unimpl This function is not supported. 
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di__apfield 
NAME 
di__apfield - append field 


SYNOPSIS 


#include "DoclC.h” 
#include “DociCProps.h” 


int 

di _apfield(to, fiprops, foprops, ret) 
di_tcont *to; 
dp_fldprops *fiprops; 


dp fontprops *foprops; /* NULL */ 
di_ field *ret; /* Returned */ 
DESCRIPTION 


The di__apfield() function is used to append a document field to the text container indicated by di__tcont. 


Refer to di__apaframe() for a description of di_tcont. Note that a field may not be appended to a heading, 
footing or numbering container. 


di_apfield() returns a handle of type di__field. This handle is passed as an argument to other di_ap*() 
functions in order to add data to the newly appended field. It cannot be specified as the di__tcont in another 
calltodi__apfield(). After appending data to a field, the field must be released by a calltodi__relfield(). 


The fiprops and foprops arguments specify field and font properties, respectively. Refer to the dp__*props 
section of this manual and the VP reference manuals for more information regarding font and field 
properties. 


The fill-in order of a fields cannot be set when they are appended to a document. To specify the fill-in order 
of fields, use the di_aptofillin() function. 


RETURN VALUE 


If the call is successful 0 is returned, otherwise -1 is returned. The function getsigno() is used to get the 
reason for the failure. 
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ERRORS 
di__apfield() will fail if one or more of the following is true: 


Doc ContainerFull There is no more room to append to this container. 
Doc DocumentFull No more room in the document. 
Doc ReadonlyDoc Document opened in ReadOnly mode. 


Doc OutOfDiskSpace Not enough disk space for the operation. 


Doc OutOfVM Not enough virtual memory for the operation. 
Doc__ObjillegalinCont Attempted to add an object of an unsupported type to a container. 
Doc _BadParm One of the specified arguments is invalid. 
Doc_IllegalHandle The specified handle is illegal. 
Doc TimeOut Inter-process communication has exceeded the maximum allowed time. 
Doc _Unimpl This function is not supported. 
SEE ALSO 


di__relfield(),di__aptofillin() 
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di__apfntile 


NAME 


di__apfntile - append footnote reference tile 
SYNOPSIS 


#include “DociC.h” 
#include “DociCProps.h” 
int 

di apfntile(to, foprops) 


~ di__text to; 
dp_fontprops *foprops; /* NULL */ 


DESCRIPTION 


The di__apfntile() function is used to append a Footnote Reference Tile to the text container specified in the 
di_text. argument. 


The foprops argument specifies the font properties of the newly generated Footnote Reference Tile. 
RETURN VALUE 


If the call is successful 0 is returned, otherwise -1 is returned. The function getsigno() is used to get the 
reason for the failure. 


ERRORS 
di_a pfntile() will fail if one or more of the following is true: 


Doc ContainerFull There is no more room to append to this container. 

Doc DocumentFull No more room in the document. 

Doc ReadonlyDoc Document opened in ReadOnly mode. 

Doc OutOfDiskSpace Not enough disk space for the operation. 

Doc OutOfVM Not enough virtual memory for the operation. 

Doc ObjillegallnCont Attempted to add an object of an unsupported type to a container. 

Doc BadParm One of the specified arguments is invalid. 

Doc_IllegalHandle The specified handle is illegal. 

Doc TimeOut Inter-process communication has exceeded the maximum allowed time. 


Doc _Unimpl This function is not supported. 
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di__apfstyle, di__appstyle 


NAME 


di__apfstyle, di__appstyle - append font and paragraph style 


SYNOPSIS 


#include “DociIC.h” 
#include "DociCProps.h” 


int 

di__apfstyle(doc, props) 
di_docdoc; 
dp_fstyleprops *props; 

int 

di__appstyle(doc, props) 
di_docdoc; 
dp__pstyleprops *props; 

DESCRIPTION 


The di_apfstyle() and di_appstyle() functions are used to append respective font and paragraph style 
properties to the styles in a document. Refer to the Document Editor: Basics User Guide for more 
information on document styles. 


There are two ways to append styles. The first way is via the styledat argument to di _ start(). It is used to 
define the style of first the new paragraph and page format characters. The second way is via calls to 
di apfstyle() and di appstyle(). These two functions are used to define subsequent style definitions. 
di__apfstyle() and di _appstyle() cannot be used to set the style of the first new paragraph and page format 
characters. 


The doc argument is a document handle that was returned by an earlier call to either di_ start() or 
di startap(). 


The props argument is a pointer of the type dp __fstyleprops or dp__pstyleprops. It specifies the properties 
desired by the user. 


RETURN VALUE 


If the call is successful 0 is returned, otherwise -1 is returned. The function getsigno() is used to get the 
reason for the failure. 


ERRORS 


di_appstyle() and di__apfstyle() will fail if one or more of the following is true: 


Doc _BadParm One of the specified arguments is invalid. 
Doc_IllegalHandle The specified handle is illegal. 


Doc TimeOut Inter-process communication has exceeded the maximum allowed time. 
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SEE ALSO 


di__enumstyle() 
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di__apindex 
NAME 
di__apindex - append index character 


SYNOPSIS 


#include “DocliC.h” 
#include “DociCProps.h” 


int 

di__apindex(to, ixprops, foprops, ret) 
di_tcont *to; 
dp indexprops *ixprops; 


dp fontprops *foprops; /* NULL */ 
di index *ret; /* Returned */ 
DESCRIPTION 


The di__apindex() function is used to append an index character to the text container specified in d i_tcont. 


Refer todi__apaframe() fora description ofdi__tcont. Note that heading, footing and numbering containers 
may not be specified. 


The ixprops and foprops arguments specify the respective index and font properties to be assigned to the 
index. 


di__apindex() returns di index, a handle that may be used by other di_a p*() calls to add data to the index 
character. The di__index handle must be released via relindex(). 


RETURN VALUE 


If the call is successful 0 is returned, otherwise -1 is returned. The function getsigno() is used to get the 
reason for the failure. 


ERRORS 
di__apindex() will fail if one or more of the following is true: 


Doc_ContainerFull There is no more room to append to this container. 

Doc DocumentFull No more room in the document. 

Doc ReadonlyDoc Document opened in ReadOnly mode. 

Doc OutOfDiskSpace Not enough disk space for the operation. 

Doc OutOfVM Not enough virtual memory for the operation. 

Doc _ObjillegalinCont Attempted to add an object of an unsupported type to a container. 

Doc _BadParm One of the specified arguments is invalid. 

Doc_IllegalHandle The specified handle is illegal. 

Doc TimeOut Inter-process communication has exceeded the maximum allowed time. 


Doc_Unimpl This function is not supported. 
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SEE ALSO 


relindex() 
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di__apnewpara 


NAME 


di__apnewpara - append new paragraph characters 


SYNOPSIS 


#include “DociC.h” 
#include “DociCProps.h” 


int 
di__apnewpara(to,prprops,foprops,num) 
di tcont *to; 


dp _paraprops *prprops; /* NULL */ 

dp fontprops *foprops; /* NULL */ 

unsigned num; has ast | 
DESCRIPTION 


The di__apnewpara() function is used to append one or more new paragraph characters to the text 
container specified inthe di__tcont argument. Refer todi__apaframe() for a description of di__tcont. 


The prprops and foprops arguments specify the respective paragraph and font properties of the new 
paragraph. If prprops is NULL, the new paragraph inherits the props of the previous paragraph. If foprops 
is NULL, the new paragraph inherits the paragraph properties of the previous paragraph. 


The num argument is a cardinal number that indicates the number of paragraph characters to be 
appended. 


The di tcont argument must contain at least one new paragraph character. The current implementation 
of this C interface automatically supplies the initial new paragraph character to the beginning of a new 
document. Additional new paragraph characters may be added. If the user adds a new paragraph 
character to the beginning of the document, only the user-supplied new paragraph character will be 
present. 


RETURN VALUE 
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If the call is successful 0 is returned, otherwise -1 is returned. The function getsigno() is used to get the 
reason for the failure. 
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ERRORS 
di _apnewpara() will fail if one or more of the following is true: 


Doc ContainerFull There is no more room to append to this container. 

Doc DocumentFull No more room in the document. 

Doc ReadonlyDoc Document opened in ReadOnly mode. 

Doc OutOfDiskSpace Not enough disk space for the operation. 

Doc OutOfVM Not enough virtual memory for the operation. 

Doc ObjillegallnCont Attempted to add an object of an unsupported type to a container. 

Doc BadParm One of the specified arguments is invalid. 

Doc_IllegalHandle The specified handle is illegal. 

Doc_ TimeOut Inter-process communication has exceeded the maximum allowed time. 


Doc _Unimpl This function is not supported. 
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di__appfc 
NAME 
di__appfc - append page format character 


SYNOPSIS 


#include “DociC.h” 
#include “DociCProps.h” 


int 

di__appfc(to, pgprops, foprops, whead, wfoot, wnum, ret) 
di__tcont *to; 
dp __pageprops *pgprops; 


dp fontprops *foprops; /* NULL */ 

dp bool whead; /* FALSE */ 

dp bool wfoot; /* FALSE */ 

dp bool wnum; /* FALSE */ 

ret__appfc *ret; /* Returned */ 
DESCRIPTION 


The di__appfc() function is used to append a page format character to the text container specified in the 
di_tcont argument. Only document, field and index containers may be used. Refer to di__apaframe() for a 
description ofdi__tcont. 


The pgprops argument specifies the format characteristics of the resulting page character. When 
specifying page margin properties for the pgprops argument, the margins must be set so that at least one 
inch is available for text. An inch is equivalent to 72 points. For example, (left margin+right margin+ 72 
<= page width), and (top margin+ bottom margin+ 72 < = page height). | 


The foprops argument specifies the font properties of the page format character. 


The whead, wfoot and wnum arguments are Boolean variables that are used to specify whether or not the 
resulting page format character will contain heading, footing , and/or numbering properties. 


di_appfe() returns ret__appfc, a structure containing the following members: 


di heading lhead; 

di heading rhead; 

di footing Ifoot; 

di footing rfoot; 

di__numbering num; 
The heading, footing and/or numbering handles will be NULL unless the user sets whead, wfoot and/or 
wnum to TRUE. | 


If the heading, footing and/or numbering handles are valid, the user can then apply them as text 
containers in calls to other di ap*() functions. If the headers are to be the same on both left and right 
pages, only Ihead should contain the heading. rhead should be left NULL. The same rule applies to Ifoot and 
rfoot. 


When specifying heading, footing or numbering, note that there are no automatic positioning parameters 
for information in headers and footers. The user must call the appropriate di__ap*() function to add the 
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desired text and to position it with standard text formatting, such as spaces, paragraph alignment, 
leading, line height, and tabs. 


Page number patterns are not recognized. To specify a page number in heading, footing, or numbering 
format parameters, insert a special character at the location in which a page number is desired. Note that 
the functiondp _getpagedel() returns this special character. 


When finished with heading, footing, and/or numbering parameters, every non-NULL parameter must be 
terminated by a call to di_relhead() ; di_relfoot() or di _relnum(), respectively. 


RETURN VALUE 


If the call is successful 0 is returned, otherwise -1 is returned. The function getsigno() is used to get the 
reason for the failure. 


ERRORS 
di_a ppfc() will fail if one or more of the following is true: 


Doc_ContainerFull There is no more room to append to this container. 

Doc DocumentFull No more room in the document. 

Doc ReadonlyDoc Document opened in ReadOnly mode. 

Doc OutOfDiskSpace Not enough disk space for the operation. 

Doc OutOfVM Not enough virtual memory for the operation. 

Doc ObjillegallnCont Attempted to add an object of an unsupported type to a container. 
Doc BadParm One of the specified arguments is invalid. 


Doc IllegalHandle The specified handle is illegal. 


Doc TimeOut Inter-process communication has exceeded the maximum allowed time. 
Doc _Unimpl This function is not supported. 
SEE ALSO 


dp__getpagedel(),di__relhead(),di__relfoot(),di__relnum() 
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di__aptext 


NAME 
di__aptext - append text 


SYNOPSIS 


#include "DociC.h” 
#include “DociCProps.h” 
#include "XString.h” 
int 
di aptext(to, text, foprops) 
~ di tcont *to; 
XString text; 
dp__fontprops *foprops; /* NULL */ 


DESCRIPTION 


The di__aptext() function is used to append the text string specified in the text argument to the text 
container specified inthe di__tcont argument. Refer todi__apaframe() for a description ofdi__tcont. 


The resulting text will have the font properties specified in the foprops argument. If foprops is left NULL 
then text will inherit the font properties of the previous paragraph. 


The text argument may not contain new paragraph characters (i.e., [set: 0, code: 35B)). 
Use the di__apnewpara() function to append new paragraph characters. 
RETURN VALUE 


If the call is successful 0 is returned, otherwise -1 is returned. The function getsigno() is used to get the 
reason for the failure. 


ERRORS 
di_a ptext() will fail if one or more of the following is true: 


Doc ContainerFull There isno more room to append to this container. 

Doc DocumentFull No more room in the document. 

Doc ReadonlyDoc Document opened in ReadOnly mode. 

Doc OutOfDiskSpace Not enough disk space for the operation. 

Doc OutOfVM Not enough virtual memory for the operation. 

Doc ObjillegalinCont Attempted to add an object of an unsupported type to a container. 

Doc BadParm One of the specified arguments is invalid. 

Doc_IllegalHandle The specified handle is illegal. 

Doc _ TimeOut Inter-process communication has exceeded the maximum allowed time. 


Doc _Unimpl This function is not supported. 
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SEE ALSO 


di__apnewpara() 
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di__aptofillin 


NAME 


di__aptofillin - append item to fill-in order 
SYNOPSIS 


#include “DociC.h” 
#include “XString.h” 


int 
di aptofillin(doc, name, type) 
~ di docdoc; 
XString name; 
di__fillintype type; 


DESCRIPTION 


The di__aptofillin() function is used to append to the fill-in order of fields and tables. Refer to the Document 
Editor: Basics User Guide for more information on fill-in orders of fields and tables. The fill-in order of 
fields cannot be set once they have been appended to a document, except by calling di__aptofillin(). 


The doc argument is a document handle that was returned by an earlier call to either di start() or 
di startap(). It contains the field or table in question. The name argument identifies the object to be added 
to the fill-in order. The type argument specifies the type of object to be added to the fill-in order. The value 
of type may be one of the following: 


Fi FIELD /* field */ 
Fl_TABLE /* table */ 
RETURN VALUE 


If the call is successful 0 is returned, otherwise -1 is returned. The function getsigno() is used to get the 
reason for the failure. 


ERRORS 
di_aptofillin() will fail if one or more of the following is true: 


Doc _BadParm One of the specified arguments is invalid. 
Doc IllegalHandle The specified handle is illegal. 


Doc TimeOut Inter-process communication has exceeded the maximum allowed time. 
SEE ALSO 


di_enumfillin(), di_clearfillin() 
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di__aptotxtink 


NAME 
di__aptotxtlnk - append item to text link 


SYNOPSIS 
#include “DociC.h” 


int 

di__aptotxtink(doc, item) 
di__doc doc; 
di_textlink *item; 


DESCRIPTION 


The di__aptotxtink() function is used to append an item to the end of the text frame link order. It may be 
either an existing text frame link order or one that had been cleared via di__cleartxtink(). Refer to the 
Document Editor: Basics User Guide for information on text frame link order. 


The doc argument is a document handle that was returned by an earlier call to either di start() or 
di__sta rtap(). It must contain the text frame handle and may, optionally, contain the text frame link order 


The item argument is a pointer of the type di_textlink. It specifies a structure whose members define the 
item to be appended and the text format parameters to be assigned that item. It contains the following 
members: 


XString name; 

int partab; 

dp bool newpara; 
dp bool newline: 
dp _ bool paratab; 


The name argument is a string that identifies the text frame in question. The remaining arguments 
are internal data for special case use, such as when appending data to a newly created VP document. 


The recommended usage is: 


1) EnablePO COMPRESSuponinvokingdi start()ordi startap(). (This will cause paginatetofill 
the text in linked text frames.) _ _ 

2) Append all of the text in the linked-text frame to the first link-order text frame. Internal data 
may be set to: 


partab = 1; 

newpara = FALSE; 
newline = FALSE; 
paratab = FALSE; 


3) Append the text-link to the document via a call to di_a ptotxtlink(). 
4) Call di__finish(). 


RETURN VALUE 


If the call is successful 0 is returned, otherwise -1 is returned. The function getsigno() is used to get the 
reason for the failure. 
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ERRORS 


di_aptotxtink() will fail if one or more of the following is true: 


Doc BadParm One of the specified arguments is invalid. 

Doc_IllegalHandle The specified handle is illegal. 

Doc_ TimeOut Inter-process communication has exceeded the maximum allowed time. 
SEE ALSO 


di__enumtxtink(), di_cleartxtink() 
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di__clearfillin 


NAME 


di__clearfillin - clear fill-in order 
SYNOPSIS 
#include “DociC.h” 
int 
di__clearfillin(doc) 
di_ doc doc; 
DESCRIPTION 
The di_ clearfillin() function is used to cancel the previously specified fill-in order of an entire document. 
The di clearfillin() function cancels the fill-in order previously specified. The doc argument is a 
document handle that was returned by an earlier call to either di__start()ordi__startap/(). 


RETURN VALUE 


If the call is successful 0 is returned, otherwise -1 is returned. The function getsigno() is used to get the 
reason for the failure. 


ERRORS 


di_clearfillin() will fail if one or more of the following is true: 


Doc BadParm One of the specified arguments is invalid. 

Doc_IilegalHandle The specified handle is illegal. 

Doc TimeOut Inter-process communication has exceeded the maximum allowed time. 
SEE ALSO 


di__aptofillin(), di__enumfillin() 
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di__cleartxtink 


NAME 


di__cleartxtlnk - clear text link 
SYNOPSIS 
#include “DocliC.h” 
int 
di_cl eartxtink(doc) 
d i_doc doc; 


DESCRIPTION 


The di_cleartxtInk() function is used to clear the text frame link order of a document. This function is 
usually called in preparation of setting the text link order viadi__aptotxtlink(). 


The doc argument is a document handle that was returned by an earlier call to either di_ start() or 
di_startap(). 


RETURN VALUE 


If the call is successful 0 is returned, otherwise -1 is returned. The function getsigno() is used to get the 
reason for the failure. 


ERRORS 
di_cleartxtInk() will fail if one or more of the following is true: 


Doc _BadParm One of the specified arguments is invalid. 
Doc_IllegalHandle The specified handle is illegal. 


Doc _ TimeOut Inter-process communication has exceeded the maximum allowed time. 
SEE ALSO 


di_aptotxtlink() 


1-28 DOCUMENT INTERFACES TOOLKIT SYSTEM REFERENCE 


DOCUMENT IC LIBRARY 


di__close 


NAME 


di__close - close a document 
SYNOPSIS 
#include “DociC.h” 
int 
di__close(docptr) 
di doc *docptr; 
DESCRIPTION 
The di__close() function is used to release the document handle of an enumerated document. Releasing the 
document handle frees the storage space originally allocated to it and sets the handle to NULL. The doc 
argument is the document handle to be terminated. 


RETURN VALUE 


If the call is successful 0 is returned, otherwise -1 is returned. The function getsigno() is used to get the 
reason for the failure. 


ERRORS 


di_close() will fail if one or more of the following is true: 


Doc BadParm One of the specified arguments is invalid. 

Doc_IllegalHandle The specified handle is illegal. 

Doc TimeOut Inter-process communication has exceeded the maximum allowed time. 
SEE ALSO 


di__open(),di__enumerate() 
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di_ enumerate 


NAME 


di__enumerate - parse contents of a document 
SYNOPSIS 


#include “DociC.h” 
#include “DociCProps.h” 


int 

di _enumerate(to, procs, cdat, mrgnum,ret) 
di__tcont *to; 
di enumprocs *procs; 


void *cdat; /* NULL */ 
dp _bool mrgnum; /* FALSE */ 
dp_bool *ret; /* Returned */ 
CALLBACK PROCEDURE 
dp__bool 
di__docproc(cdat, foprops, prprops, pgprops, lhead, rhead, Ifoot, rfoot, num) 
void *cdat; 


dp fontprops *foprops; 
dp paraprops *prprops; 
dp pageprops *pgprops; 
di heading Ihead; 

di heading rhead; 

di footing Ifoot; 

di footing rfoot; 
di__numbering num; 


dp bool 
di __aframeproc(cdat, type, font, frame, props, cont, tcap, bcap, Icap, rcap) 
void *cdat; 


di aframetype type; 
dp fontprops *font; 

di ins frame; 

dp frameprops *props; 
di ins cont; 

di caption tcap; 

di caption bcap; 

di caption Icap; 

di caption rcap; 


dp bool 
di__breakproc(cdat, foprops, brprops) 
void *cdat; 


dp_fontprops *foprops; 
dp__breakprops *brprops; 


1-30 | | DOCUMENT INTERFACES TOOLKIT SYSTEM REFERENCE 


DOCUMENT IC LIBRARY 


dp bool 
di tieldproc(cdat, foprops, fiprops, field) 
void *cdat; 


dp_fontprops *foprops; 
dp fidprops *fiprops; 
di tield field; 


dp bool 
di fntileproc(cdat, foprops) 
~ void *cdat; 
dp_fontprops *foprops; 


dp bool 
di indexproc(cdat, foprops, ixprops, index) 
~ void *cdat; 


dp__fontprops *foprops; 
dp indexprops *ixprops; 
di index index; 


dp_bool 
di _newparaproc(cdat, foprops, prprops) 
void *cdat; 


dp_fontprops *foprops; 
dp __paraprops *prprops; 


dp bool 
di pfcproc(cdat, foprops, pgprops, lhead, rhead, Ifoot, rfoot, num) 
~ void *cdat; 
dp fontprops *foprops; 
dp pageprops *pgprops; 


di heading Ihead; 
di heading rhead; 
di footing Ifoot; 
di footing rfoot; 
di numbering num; 
dp bool 
di sfbrkproc(cdat, num) 
~ void *cdat; 
dp _pagenumber num; 


dp bool 
di textproc(cdat, foprops, text) 
~ void *cdat; 
dp fontprops *foprops; 
XString text; 
DESCRIPTION 


The di enumerate() function is used to parse the contents of a document. 


The di tcont argument is to contain the file handle returned by an earlier call to di_ open(). Refer to 
di_apafra me() for a description of di__tcont. 


The cdat argument is a pointer to any user-defined data that is passed to the call-back procedure(s) 
specifiedinthedi__enumprocsargument. 


DOCUMENT INTERFACES TOOLKIT SYSTEM REFERENCE 1-31 


DOCUMENT IC LIBRARY 


The mrgnum argument is short for “merge numbering”. It is a Boolean value that, when set to TRUE, 
indicates that a page numbering pattern will be included in the heading or footing during enumeration. 
Setting this value to TRUE will result inthecorrespondingdi numberingindi pfcprocanddi docproc to 
be set to NULL. _ _ _ 


The di_enumprocs argument is a structure that contains user-defined call-back procedures for 
enumerating objects in the specified file. The members of di__enumprocs are: 


di docproc *doc; 

di aframeproc *aframe; 

di breakproc *break; 

di fieldproc *field; 

di fntileproc *fntile; 

di indexproc *index; 

di newparaproc *newpara; 
di pfcproc *pfc; 

di sfbrkproc *sfbrk; 
di__textproc *text; 


Each call-back procedure specified in di enumprocs uses the properties and contents of the structure as 
parameters when invoked. The storage resources allocated to the properties passed to these functions is 
temporary; the user must explicitly copy any properties he or she may wish to save. 


Ifdocis not NULL, di__docproc() will be called first with the first foprops, prprops, and pgprops present in 
the document. If doc is NULL, di__newpara proc() will be called and then di_pfcproc will be called with the 
first foprops, prprops, and pgprops present in the document. 


When calling di__pfcproc(), if the headers are identical on the left and right pages, only Ihead will contain 
the heading; rhead must remain NULL. The same rule applies to Ifoot and rfoot. 


Each call-back procedure returns a Boolean value. Enumeration stops when a return value is TRUE. 


Some of the call-back procedures require a text container handle as a parameter. The text container 
handle may be specified recursively in calls todi enumerate() in order to extract the contents of that same 
text container. For example,di_ fieldprocmaycalldi enumerate() with field as the text container in order 
to extract the contents of the field. di enumerate() requires a text container of type di tcont. di cont 
contains a union of two members: type and h. type is to be set to TC FIELD and h is to be set to the field 
that was passed byacalltodi_fieldproc. 


Any handle returned by a call-back procedure is read only, and is valid only during the invocation of the 
call-back procedure. The handle returned is automatically released after execution of the call-back 
procedure. When a NULL handle is returned, it means the corresponding object does not contain text. 


The initial paragraph and page format characters in a text container are also enumerated. Thus, when 
copying an existing document into a new document, avoid copying the initial paragraph and page format 
characters of the existing document as you copy the remainder of its contents. 


RETURN VALUE 
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If the call is successful 0 is returned, otherwise -1 is returned. The function getsigno() is used to get the 
reason for the failure. 
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ERRORS 


di _enumerate() will fail if one or more of the following is true: 
Doc BadParm One of the specified arguments is invalid. 


Doc_illegalHandle The specified handle is illegal. 


Doc TimeOut Inter-process communication has exceeded the maximum allowed time. 


SEE ALSO 


di__open(),di__textforaframe(), di__close() 
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di__enumfillin 
NAME 

di__enumfillin - enumerate fill-in order 
SYNOPSIS 

#include “DoclIC.h” 

int 

di__enumfillin(doc, proc, cdat) 

di docdoc; 


di fillinproc *proc; 
void *cdat; /* NULL */ 


CALLBACK PROCEDURE 


dp bool 
di fillinproc(cdat, name, type) 
~ void *cdat; 
XString name; 
di_fillintype type; 
DESCRIPTION 


The di__enumfillin() function is used to enumerate the fill-in order of fields and tables. 
The doc argument is a document handle that was returned by an earlier call todi_ open() or di_ startap(). 


The proc argument is a pointer of the type di__fillinproc(). It specifies a call-back procedure to be invoked 
once for each object in the fill-in order. The arguments passed to proc specify user-defined data, the name 
of the enumerated object and its type. di_fillinproc may return True to halt the enumeration. 


RETURN VALUE 


If the call is successful 0 is returned, otherwise -1 is returned. The function getsigno() is used to get the 


reason for the failure. 
ERRORS 
di_enumfillin() will fail ifone or more of the following is true: 


Doc BadParm One of the specified arguments is invalid. 


Doc_IllegalHandle The specified handle is illegal. 


Doc TimeOut Inter-process communication has exceeded the maximum allowed time. 


SEE ALSO 


di__aptofillin(), di__clearfillin() 
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di_ enumstyle 


NAME 


di__enumstyle - enumerate style 
SYNOPSIS 


#include “DocIC.h” 
#include “DociCProps.h” 


int 
di enumstyle(doc, fstyleproc, pstyleproc, cdat) 
~ di docdoc; 
di fstyleproc *fstyleproc; 
di pstyleproc *pstyleproc; 
void *cdat; /* NULL */ 


CALLBACK PROCEDURE 
dp bool 
di__fstyleproc(cdat, props) 

void *cdat; 
dp_fstyleprops *props; 
dp bool 
di__pstyleproc(cdat, props) 
void *cdat; 
dp_pstyleprops *props; 
DESCRIPTION 


The di__enumstyle() function is used to enumerate all the font and paragraph style properties of a 
document, such as mode, fill-in order,and text-link. 


The doc argument is a document handle that was returned by an earlier call todi__open() ordi__startap/(). 
The fstyleproc and pstyleproc arguments are pointers to d i_fstyleproc and di__pstyleproc, respectively. 
These call-back procedures are invoked once for each object in the style.They are invoked at the onset of 
di__enumstyle()’s execution, and, if either call-back procedure returns TRUE, the document enumeration 
process is aborted. If FALSE is returned, the process continues until completed. 

The cdat argument is user-defined data that is passed to fstyleproc and pstyleproc. 


RETURN VALUE 


If the call is successful 0 is returned, otherwise -1 is returned. The function getsigno() is used to get the 
reason for the failure. 
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ERRORS 


di__enumstyle() will fail if one or more of the following is true: 


Doc _BadParm One of the specified arguments is invalid. 

Doc_IllegalHandle The specified handle is illegal. 

Doc TimeOut Inter-process communication has exceeded the maximum allowed time. 
SEE ALSO 


di_apfstyle(),di__appstyle() 
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NAME 


di__enumtxtlnk - enumerate text link 
SYNOPSIS 
#include "DoclC.h” 


int 
di enumtxtink(doc, proc, cdat) 
~ di docdoc; 
di txtInkproc *proc; 
void *cdat; /* NULL */ 


CALLBACK PROCEDURE 
dp__bool 
di_txtInkproc(item, cdat) 

di textlink *item; 
void *cdat; 


DESCRIPTION 


The di _enumtxtink() function is used to enumerate the link order of a text frame. 
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The doc argument is a document handle that was returned by an earlier call todi_open() ordi__startap(). 
It contains the text link order and text frame in question. If the text-link order is not included, 


di__txtlnkproc will not be called. 


The proc argument is a pointer of the type di 


txtIinkproc. It contains a call-back procedure that is invoked 


at the onset of di enumtxtink()’s execution, and, if it returns TRUE, the enumeration process is aborted. If 


FALSE is returned, the process continues until completed. 


The cdat argument is user-defined data that is passed to proc. 


RETURN VALUE 


If the call is successful 0 is returned, otherwise -1 is returned. The function getsigno() is used to get the 


reason for the failure. 


ERRORS 


d i_enumtxtink() will fail if one or more of the following is true: 


Doc_BadParm One of the specified arguments is invalid. 


Doc_IllegalHandie The specified handle is illegal. 


Doc TimeOut Inter-process communication has exceeded the maximum allowed time. 


SEE ALSO 


di_a ptotxtink(), di__clea rtxtink() 
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di__ finish 
NAME 

di__finish - finalize the document 
SYNOPSIS 


#include “DociC.h” 


int 
di__finish(doc, proc, cdat, ret) 


di__doc *doc; 
di ckabortproc*proc; /* NULL */ 


void *cdat; /* NULL */ 
ret__ fe *ret; /* Returned */ 
CALLBACK PROCEDURE 
dp bool 


di__ckabortproc(cdat) 
void *cdat; 


DESCRIPTION 
The di__finish() function is used to finalize the document and to release the document handle, doc. 
The doc argument is the file handle that was returned by an earlier call to either di__start()ordi__startap(). 
The proc argument is a pointer of the type di__ckabortproc. It is a user-defined call-back procedure which 
can be used to abort the document generation process. It is invoked at the onset of di__finish()’s execution, 


and, if di__ckabortproc returns TRUE, the document generation process is aborted. If FALSE is returned, the 
process continues until completed. 


The cdat argument is user-defined data that is passed to di__ckabortproc. 
di_finish() returns ret__ fc, a structure comprised of the following members: 


dsktp__docref ref; 
di_fcstat stat; 


The first member, dsktop__docref, is the reference handle of the newly created document. This handle 
may be passed as an argument todsktp movedoc() to place the document on the desktop or in a folder. 
The second member, status, indicates the success or failure of the operation. status may one of the 


following values: 
FC OK No errors were encountered. 
FC ABORT Was unable to complete the document. 


FC DSKSP,FC_VM,FC_ UNKNOWN The document is finished but left unpaginated. 


The resulting document file is temporary. To make the file permanent, call the dsktp movedoc() function. 
It will place the document on the desktop or in a folder. The document that di_finish() provides will be in 
paginated form if the appropriate pagination parameters were specified in the initial call di__start() or 
di startap/(). 
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RETURN VALUE 


If the call is successful 0 is returned, otherwise -1 is returned. The function getsigno() is used to get the 
reason for the failure. 


ERRORS 


di__finish() will fail if one or more of the following is true: 


Doc BadParm One of the specified arguments is invalid. 
Doc_IllegalHandle The specified handle is illegal. 


Doc_ TimeOut Inter-process communication has exceeded the maximum allowed time. 


SEE ALSO 


di__start(),di__startap(),dsktp _movedoc() 
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di__getfieldfromname 


NAME 
di__getfieldfromname - extract the properties of a named field 
SYNOPSIS 
#include “DociC.h” 
#include “DociCProps.h” 
#include “XString.h” 
int 
di_getfieldfromname(doc, name, props) 
di_docdoc; 
XString name; 
dp_fidprops *props; 
DESCRIPTION 


The di__getfieldfromname() function is used to search for a named field and list the properties of that field, 


The di__doc argument contains a document handle that was returned by an earlier call to di__open(), 
di__start()ordi__startap(). 


The name argument is a string that specifies the name of the field from which to extract properties. 


The props argument is a pointer of the type dp fldprops. It specifies a list of the field properties to be 
extracted from the named field. ~ 


RETURN VALUE 


If the call is successful 0 is returned, otherwise -1 is returned. The function getsigno() is used to get the 
reason for the failure. 


ERRORS 
di_getfieldfromna me() will fail if one or more of the following is true: 


Doc BadParm One of the specified arguments is invalid. 
Doc IllegalHandle The specified handle is illegal. 


Doc TimeOut Inter-process communication has exceeded the maximum allowed time. 
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di__getfnprops 


NAME 


di_ 


getfnprops - get footnote properties 


SYNOPSIS 


#include “DociC.h” 
#include “DociCProps.h” 


int 
di getfnprops(doc, procs, cdat) 
~ di docdoc; 
di fnpropsproc * procs; 
void *cdat; /* NULL */ 
CALLBACK PROCEDURE 
int 
di fnpropsproc(cdat, nmprops, frprops, tfprops, foprops, pattern) 
~ void *cdat; 
dp fnnumprops *nmprops; 
dp frameprops *frprops; 
dp tframeprops *tfprops; 
dp fontprops *foprops; 
di text pattern; 
DESCRIPTION 


The di__getfnprops() function is used to obtain the footnote properties of the document. 


The doc argument is a document handle that was returned by an earlier call to di_open() or di__sta rtap(). 


The procs argument is a pointer of the type di fnpropsproc. It is a call-back procedure that is invoked 
with all the footnote properties in the specified document. di__fnpropsproc does not need to call di_reltext() 
to release the text handle. 


The cdat argument is a pointer to user-defined data. 


RETURN VALUE 


If the call is successful 0 is returned, otherwise -1 is returned. The function getsigno() is used to get the 
reason for the failure. 


ERRORS 


di__getfnprops() will fail if one or more of the following is true: 


DOCUMENT INTERFACES TOOLKIT SYSTEM REFERENCE 


Doc BadParm One of the specified arguments is invalid. 
Doc_IllegalHandle The specified handle is illegal. 


Doc TimeOut Inter-process communication has exceeded the maximum allowed time. 
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SEE ALSO 


di__setfnprops() 
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di__open 
NAME 
di__open - open a document 


SYNOPSIS 


#include “DocliC.h” 
#include “Desktop.h” 


int 
di open(ref, ret) 
~ dsktp docref ref; 
ret_ open *ret; 


DESCRIPTION 
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/* Returned */ 


The di__open() function is used to obtain the handle of a specific file. The returned file handle may then be 
passed as an argument todi_enumerate(), a function used to extract the contents of a file. 


The ref argument is the handle of the document to be opened and is of the type dsktp docref. ref is the 
document reference handle returned by an earlier call to dsktp__getdocref(), dsktp__copydoc() or 


dsktp _enumerate(). 


di_open() returns ret__Open, a structure that contains the following members: 


di_doc doc; 
di__opstat status; 


doc is a document handle that may be passed to di _enumerate(). status is a code whose value indicates 
the success of the operation. The returned status code may be one of the following: 


OP OK 
OP_MALFORM 
OP_INCOMP 


OP_NOTLOCAL 
OP_DSKSP 
OP_VM 
OP_BUSY 

OP PASSWD 


RETURN VALUE 


No errors were encountered. 
The Document is inconsistent internally. 


The version of the Document Editor used to open a document is different than 
the version used to create it. 


The document is not on the local workstation, so it cannot be opened. 
Available disk space is insufficient to open the document. 

Available contiguous virtual memory is insufficient to open the document. 
Another process is using the file (e.g. background pagination). 


The user has invalid or incorrect credentials for opening the document. 


If the call is successful 0 is returned, otherwise -1 is returned. The function getsigno() is used to get the 


reason for the failure. 
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ERRORS 
di _open() will fail if one or more of the following is true: 


Doc BadParm One of the specified arguments is invalid. 
Doc _IllegalHandle The specified handle is illegal. 


Doc TimeOut Inter-process communication has exceeded the maximum allowed time. 
SEE ALSO 


di__enumerate(), di__close() 


1-44 DOCUMENT INTERFACES TOOLKIT SYSTEM REFERENCE 


DOCUMENT IC LIBRARY 


di__rel* 


NAME 


di__relcap, di_ relfield, di__relfoot, di_ relhead, di__relnum, di_ relindex, di__reltext - release storage 
SYNOPSIS 
#include "DociC.h” 


int 
di_relcap(cap) 
di_ caption *cap; 


int 
di_relfield(field) 
di__ field *field; 


int 
d i_relfoot(foot) 
di_ footing *foot; 


int 
di_relhead(head) 
di heading *head; 


int 
di_relnum(num) 
di__numbering *num; 


int 
di_relindex(index) 
di_index *index; 
int 
di_reltext(text) 
di__text *text; 
DESCRIPTION 


These functions are used to terminate handles, thus releasing the resources assigned to the respective 
handle. The user mustcalldi__relcap(),di__relfield(),di__relfoot(),di_ relhead(),di__relnum(),di__relindex(), 
or di reltext() to release the resources associated with a non-NULL handle obtained from any di ap*() 
function. _ 


After calling di__rel*(), the respective handle will be invalid. To help prevent the use of an invalid handle, 
each di__rel*() routine removes the pointer to the respective handle and then sets the handle itself to NULL. 


RETURN VALUE 


If the call is successful 0 is returned, otherwise -1 is returned. The function getsigno() is used to get the 
reason for the failure. 
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ERRORS 


di__rel*() will fail if one or more of the following is true: 


Doc BadParm One of the specified arguments is invalid. 


Doc_IllegalHandle The specified handle is illegal. 


Doc TimeOut Inter-process communication has exceeded the maximum allowed time. 
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di__setfnprops 


NAME 


di__setfnprops - set footnote properties 
SYNOPSIS 


#include “DociC.h” 
#include “DociCProps.h” 


int 
di setfnprops(doc, nuprops, frprops, tfprops, foprops, ret) 
~ di docdoc; 
dp fnnumprops*nuprops; /* NULL */ 
dp frameprops *frprops; /* NULL */ 
dp tframeprops*tfprops; /* NULL */ 


dp _fontprops *foprops; /* NULL */ 
di_text *ret; /* Returned */ 
DESCRIPTION 


The di__setfnprops() function is used to set the footnote properties of a document. 


The doc argument is a document handle that was returned by an earlier call to either di start() or 
di startap/(). 


The nuprops argument is a pointer of the type dp_fnnumprops. It is a structure containing data used to 
control the numbering of footnotes across documents during pagination of a book or a shared book. 


The frprops argument is a pointer of the type dp__frameprops. It is a structure containing data that 
specifies the values of footnote frame properties, such as border thickness, number of columns to span, and 
margin control. 


The tfprops argument is a pointer of the type dp tframeprops. It is a structure that specifies the text 
frame properties, such as orientation and name. 


The foprops argument is a pointer of the type dp fontprops. It is a structure that specifies the font 
properties to be used in the footnotes, such as font type, placement, and offset. 


This function returns di__text, a handle that may be passed to other di _ap*()functions. Thedi__ text handle 
must be released via di _ reltext(). 


RETURN VALUE 


If the call is successful 0 is returned, otherwise -1 is returned. The function getsigno() is used to get the 
reason for the failure. 
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ERRORS 
di__setfnprops() will fail if one or more of the following is true: 


Doc BadParm One of the specified arguments is invalid. 
Doc_IllegalHandle The specified handle is illegal. 


Doc TimeOut Inter-process communication has exceeded the maximum allowed time. 


SEE ALSO 


di_getfnprops(), di_reltext() 
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di__setmode, di__getmode 


NAME 


di__setmode, di__getmode, - set or get the mode of properties for the document 
SYNOPSIS 


#include “DocIC.h” 
#include “DociCProps.h” 
int 
di getmode(doc, props) 
~ di docdoc; 
dp _modeprops *props; 
int 
di setmode(doc, props, select) 
~ di docdoc; 
dp modeprops ‘props; 
dp __modesel select; 


DESCRIPTION 
These two functions are used, either, to get or to set the mode properties of a document. Mode properties 
are Boolean variables that, when set to TRUE, display the structure, non-printing characters, cover sheet, 


and prompt fields in a document. These functions may be called at any time during the document 
generation process. 


The di__doc argument is the document handle that was returned by an earlier call to di__start() or 
di_startap(). 


dp modeprops is an argument that points to a structure containing four Boolean fields that indicates the 
different display characteristics of the document in question. 


The dp__modesel argument is an array that is used to specify those display characteristics to be affected. 
When setting mode properties, only those properties designated by TRUE selections will be changed. 


RETURN VALUE 


If the call is successful 0 is returned, otherwise -1 is returned. The function getsigno() is used to get the 
reason for the failure. 


ERRORS 
di_setmode() and di_getmode() will fail if one or more of the following is true: 


Doc BadParm One of the specified arguments is invalid. 
Doc_IllegalHandle The specified handle is illegal. 


Doc TimeOut Inter-process communication has exceeded the maximum allowed time. 
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di__setpara 


NAME 


di__setpara - set current paragraph properties 


SYNOPSIS 


#include “DociC.h” 
#include “DociCProps.h” 


int 

di_setpara(to, prprops) 
di__tcont *to; 
dp _paraprops “prprops; 


DESCRIPTION 


The di__setpara() function is used to modify the paragraph properties of paragraphs in a specific text 
container. This function may be called at any time. If it is called repeatedly in the same paragraph, only 
the most recent call will remain in effect. 


The di__tcont argument is the handle to the text container whose paragraph properties are to be modified. 
The text container may be any di__tcont or document. Refer todi__apaframe() for a description of d i__tcont. 


The di paraprops argument points to a structure containing the set of paragraph properties to be 
modified. 


di__setpara() affects the entire current paragraph, including portions not yet appended at the time 
di__setpara() is called. The property changes are also applied to all subsequent paragraphs unless the user 
overrides the properties with new ones passed to di__apnewpara(), or by another call to di__setpara(). 


Setting text container paragraph properties will result in an error if the text container in question does 
not contain at least one paragraph character. Although paragraph characters are added (as necessary) 
duringcallstodi ap*(),callingdi setpara()beforecallinganydi ap*()function willresultinanerror. To 
avoid this situation, the user may simply call di apnewpara() to ensure that the di tcont does have a 
paragraph character. di ap*() functions will add a new paragraph character only if there is none already 
present, thus avoiding any duplication. 


RETURN VALUE 


If the call is successful 0 is returned, otherwise -1 is returned. The function getsigno() is used to get the 
reason for the failure. 


ERRORS 
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di_setpa ra() will fail if one or more of the following is true: 


Doc BadParm One of the specified arguments is invalid. 
Doc _ IllegalHandle The specified handle is illegal. 


Doc TimeOut Inter-process communication has exceeded the maximum allowed time. 


DOCUMENT INTERFACES TOOLKIT SYSTEM REFERENCE 


DOCUMENT IC LIBRARY 


SEE ALSO 


di _apnewpara() 
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di__start 


NAME 


di__ start - begin creation of a new document 
SYNOPSIS 


#include “DociC.h” 
#include “DociCProps.h” 


int 
di start(pagiops, whead, wfoot, wnum, ifoprops, iprprops, ipgprops, styledat, ret ) 
~ di pagiops pagiops; /*PQ COMPRESS */ 
dp bool whead; /* FALSE */ 
dp bool wfoot; /* FALSE */ 
dp bool wnum; /* FALSE */ 
dp fontprops *ifoprops; /* NULL */ 
dp paraprops *iprprops; /* NULL */ 
dp pageprops *ipgprops; /* NULL */ 
di styledata *styledat; /* NULL */ 
ret sc *ret; /* Returned */ 
CALLBACK PROCEDURE 
int 


di styleproc(style,cdat, fstyleproc, pstyleproc) 
~ di style style; 
void *cdat; 
di apfstyleproc *fstyleproc; 


di__appstyleproc *pstyleproc; 


int 

di_apfstyleproc(style,styleprops) 
di__style style; 
dp_fstyleprops *styleprops; 


int 
di_appstyleproc(style,styleprops) 
di__style style; 
dp __pstyleprops *styleprops; 


DESCRIPTION 


The di start() function is called to initiate the document generation process. It is used to create an empty 
document with specific format attributes, such as pagination and margin size. It then returns a file handle 
that needs to be passed as an argument torelateddi ap*()functions. di finish() is called to terminate the 
document generation process initiated by di__start(). _ 


The pagiops argument specifies the type of pagination the finished document is to have. It may have one 
of three possible values: PO COMPRESS, PO_ SIMPLE, and PO__NONE. 


PO COMPRESS pagination provides all the outward signs of pagination, such as page format 


properties, and leaves the structure of the document in an optimized form. An optimized document 
occupies less disk and buffer space than an unoptimized document. 
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PO __ SIMPLE pagination provides the outward signs of pagination but does not leave the document in an 
optimized form. Therefore, subsequent editing may be slower than it would be for documents 
paginated with PO COMPRESS. The advantage of this option over PO COMPRESS is that this option 
completes the pagination process slightly faster than does PO COMPRESS. 


PO NONE skips the pagination process entirely, thus leaving the document in a raw form. Raw form 
means that the document is neither paginated nor optimized. This may result in slow editing and 
potential loss of data. This option is recommended for only very small documents. If the document is to 
be more than a few pages in length, the user must specify a pagiops value other than PO_ NONE to 
avoid losing data. 


The whead, wfoot and wnum arguments are Boolean values that,when set to TRUE, insert heading, 
footing, and numbering properties into the first page format character (PFC) of the document. 


The ifoprops, iprprops, and ipgprops arguments specify the initial font, paragraph, and page properties of 
the document, respectively. If these arguments are left NULL, di__start() will use a default set of properties. 
Refer todp__*props for more information regarding properties and their default values. 


When specifying the field properties for the ipgprops argument, page margins must be set so that at least 
one inch is left for text. An inch is the equivalent of 72 points. For example, (left margin+ right 
margin+ 72 <= page width), and (top margin + bottom margin+ 72 < = page height). 


The styledat argument is a pointer of type di styledata. It is a structure used to call the call-back 
procedure, di styleproc. The call-back procedure specifies the font and paragraph style properties of the 
new document. The styledat argument applies only to the first new paragraph and page format characters 
in the document. di__styledata contains the following members: 


di__styleproc *styleproc; 
void *cdat; 


If styledat is a non-NULL value, the user-defined call-back procedure will be called before a document 
handle is returned. 


Another way to add font and paragraph style properties is by calls to di apfstyle() and di appstyle(), 
Their full names are AppendFontStyle and AppendParagraphStyle, respectively. Note that properties for 
the first new paragraph character and the page format character can be set only by the styledat 
argument, not by the di__apfstyle() or the di__appstyle() functions. 


di__start() sets the return information into the structure ret_ sc, which contains the following members: 


di docdoc; 

di heading lhead; 
di heading rhead; 
di footing Ifoot; 

di footing rfoot; 

di numbering num; 
di scstat stat; 


The di__doc handle returned represents the new document. The user should pass this handle to 
di__ap*() functions to add information to the document. The handle is later released by a call to 
di finish(). 
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If the user releases the handle without calling a di__ap*() function, the resulting file will be a 1-page 
document containing a single new paragraph and page format character, with the initial font, 
paragraph, and page props as specified in ifoprops, iprprops, and ipgprops, respectively. 


di heading,di footing,anddi numbering areheading, footingandnumbering handles, respectively. 
They will be NULL unless the user specified whead, wfoot or wnum = TRUE. If the headings, footings 
or numbering are valid, the user should call various di ap*() routines to add text and formatting 
information, and then later release each handle witha call to di_relhead(), di__relfoot() or di_relnum(). 


stat is a status code, which can have any of the following values: 


s¢c_ OK No errors were encountered. 

SC__DSKSP There is not enough disk space to perform the operation. 

sc_VM There is not enough contiguous virtual memory to create. 
RETURN VALUE 


If the call is successful 0 is returned, otherwise -1 is returned. The function getsigno() is used to get the 
reason for the failure. 


ERRORS 


di__start() will fail if one or more of the following is true: 


Doc BadParm One of the specified arguments is invalid. 

Doc_IllegalHandle The specified handle is illegal. 

Doc TimeOut Inter-process communication has exceeded the maximum allowed time. 
SEE ALSO 


di__finish(),di__ap*(),di_ relhead(), di__relfoot(), di__relnum() 
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di__startap 


NAME 
di__startap - start appending 


SYNOPSIS 


#include “DociC.h” 
#include “Desktop.h” 


int 
di__startap(ref, pagiops, ret) 
dsktp_docref ref; 
di__pagiops pagiops; /*PQ__COMPRESS */ 
ret__startap ‘ret; /* Returned */ 
DESCRIPTION 


The di__startap() function is called to acquire a file handle that may be used by other di _ap*() procedures 
to append data to the end of an existing document. 


The ref argument specifies the file that is to be opened. The pagiops argument specifies the type of 
pagination the appended data is to have. See di__start() for information regarding the construction of the 
pagiops argument. 


ret__startap is returned and it contains the following members: 


di_doc doc; 
di_scstat status; 


doc is a file handle for the document that is to have data appended. 
status indicates the success of the di__startap() call. It may have any of the following values: 


sc_OK No errors were encountered. 
SsC__DSKSP There is not enough disk space to perform the operation. 
sc_VM There is not enough contiguous virtual memory to create. 


sC__BUSY Another process is accessing the file. 


When appending is complete, di _ finish() must be called to release the doc handle. If the status returned is 
not SC_OK, then the doc handle will be NULL and di__finish() should not be called. 


RETURN VALUE 


If the call is successful 0 is returned, otherwise -1 is returned. The function getsigno() is used to get the 
reason for the failure. 
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ERRORS 


di__startap() will fail if one or more of the following is true: 


Doc _BadParm One of the specified arguments is invalid. 

Doc_IllegalHandle The specified handle is illegal. 

Doc TimeOut Inter-process communication has exceeded the maximum allowed time. 
SEE ALSO 


di_start(), di_finish() 
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di__starttext 


NAME 
di__starttext - begin appending text 


SYNOPSIS 


#include “DociC.h” 
#include “DociCProps.h” 


int 
di starttext(doc, frame, props, ret) 
~ di docdoc; 
di ins frame; 
dp tframeprops *props; 
di text *ret; 
DESCRIPTION 


Thedi starttext() function is used to initiate the process of appending text to the body of an anchored text 
frame. di starttext() readies an anchored text frame to accept new text, then returns an object handle 
which may be passed to any other di ap*() operation. Once the data has been appended to the frame, the 
user should call di__reltext() with the text handle returned by di__starttext(). 


The doc argument is the document handle returned by an earlier call to either di start() or di startap(). 
The frame argument is the frame handle returned by an earlier call to di apaframe(). The props 
argument describes the text frame properties. Refer to DocICProps for more information regarding text 
frame properties. 


Itisnot mandatory tocalldi starttext() after calling di_a paframe(). Failuretocalldi starttext() will only 


result in an empty text frame. The frame will be entirely empty except for the presence of one new 
paragraph character that has default paragraph and font properties. 


RETURN VALUE 


If the call is successful 0 is returned, otherwise -1 is returned. The function getsigno() is used to get the 
reason for the failure. 


ERRORS 


di__starttext() will fail if one or more of the following is true: 


Doc BadParm One of the specified arguments is invalid. 

Doc_IllegalHandle =The specified handle is illegal. 

Doc_ TimeOut Inter-process communication has exceeded the maximum allowed time. 
SEE ALSO 


di_apaframe(), di_reltext() 
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di__textforaframe 


NAME 


di__textforaframe - retrieve text from an anchored frame 


SYNOPSIS 


#include “DociC.h” 
#include “DociCProps.h” 


int 
di textforaframe( cont, props, ret) 
~ di ins cont; 
dp tframeprops *props; 
di text *ret; /* Returned */ 


DESCRIPTION 


The di__textforaframe() function is used to extract text from an anchored frame during enumeration. The 
contents of the text handle returned by this function may be enumerated by supplying the text handle as 
an argument to di__enumerate(). After enumeration, call di_reltext() to release the text handle. 


The cont argument is an instance of an anchored frame. This instance is supplied as an argument to the 
di__aframeproc call-back procedure. 


The props argument is a pointer of the type dp tframeprops. It is a structure that specifies a set of text 
frame properties. Text frame properties, such as name and description, are used to identify the frame in 
question. Since the text container passed from di aframeproc is not unique for each enumeration, the 
instance handle alone cannot be used to identify the frame in question. 


The frame to be enumerated cannot be in a document to which any object has been appended.This means 
that the frame instance that is returned by a call to di aframeproc cannot be used be passed as the 
container to di textforaframe(). To append an object to the frame that is returned by 
di__enumerate(di__aframeproc()): 


1) Enumerate the source text frame viaacalltodi textforaframe(). 

2) Initialize the frame to which the text is to be appended via acalltodi starttext(). 

3) Enumerate the source text and append it to the target frame viaacalltodi textproc(call-back). 
4) Release the text handles returned via calls to di__reltext(). 7 


RETURN VALUE 


If the call is successful 0 is returned, otherwise -1 is returned. The function getsigno() is used to get the 
reason for the failure. 


ERRORS 
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di__textforafra me() will fail if one or more of the following is true: 


Doc BadParm One of the specified arguments is invalid. 
Doc _ IllegalHandle The specified handle is illegal. 


Doc TimeOut Inter-process communication has exceeded the maximum allowed time. 
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SEE ALSO 


di _enumerate(), di_reltext() 
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2: Document IC Property Library 


dp__intro 


NAME 


dp__intro - introductory explanation of Document IC properties 
DESCRIPTION 


This library contains functions and data types used to describe document-related properties. The 
properties described below contain information that applies to all *IC interfaces. 


Break Properties 


The chief type in this section is dp__breakprops. It describes the properties of the page break character. 
dp__breakprops contains the following member: 


dp__breaktype type; 


dp__breaktype may have one of the following values: 


BR _NPAGE /* new page */ 

BR_NLPAGE /* new left page */ 

BR _NRPAGE /* new right page */ 

BR NCOL /* new column */ 
Field Properties 


The chief field property is dp_fldprops. It describes the properties of a field character. dp__fldprops 
contains the following members: 


dp _ lang lang; 
unsigned length; 

dp bool req; 

dp skpchoice skpif; 
dp bool stpskp; 

dp fldchoice type; 
XString fillin; 
XString desc; 
XString format; 
XString name; 
XString range; 
XString skpiffid; 
dp__fontruns *fillinruns; 


lang is the value ofdp__lang, an enumerated type used to specify the alphabet that will be used, based 
upon nationality, to generate text in the date and amount fields. 
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length specifies the maximum number of logical characters the field may contain. 


req specifies whether the user is required to fill in the field being generated. If req is TRUE, the user will 
not be able to use NEXT or SKIP to advance to the next field until this field has been given a value. 


skpif specifies the conditions under which the user may press either the NEXT or SKIP button to skip 
the field. stpskp specifies the conditions under which the NEXT or SKIP buttons will be disabled. skpif 
may have one of the following values: 


SKP EMPTY /* skip if the field is empty */ 
SKP NOTEMPTY /* skip if the field is not empty */ 
SKP NEVER /* never */ 

SKP_ ALWAYS /* always */ 


type is the value ofdp fldchoice, an enumerated type that specifies the kind of data to be placed in the 
field. It may have one of the following values: 


FLD ANY /* any */ 
FLD TEXT /* text */ 
FLD AMOUNT /* amount */ 
FLD DATE /* date */ 


FLD ANY indicates that the field may contain any characters, including frames (but not other 
fields). FLD TEXT indicates that the field may contain only letters, digits, and symbols entered 
from the keyboard. FLD AMOUNT indicates that the field may contain only numbers, spaces, and 
the following symbols:+__ *$,.(). FLD DATE specifies that entries in the field may contain only a 
date. 


fillin defines the fill-in rule for this field. 


If the document is set to prompt for data to go in fields upon pressing the NEXT key, desc specifies the 
message that is to be displayed as the prompt. 


format controls the format in which information is presented. It is affected by the value of type. For a 
type of FLD TEXT, this property defines a required pattern that must be matched. For a type of 
FLD AMOUNT or FLD DATE, this field controls the form in which the contents of the field will be 
presented, regardless of how the user enters it. For a type of FLD_ ANY, the format property will not be 
used. 


name is the text name to be assigned to the field. If no name is provided, the field will automatically be 
named Fieldn, as in Field1, Field2, and so on. 


range defines a specific range of acceptable entries. For example, if A ctnl C is specified, where ctnl is 
the control character, the D field may not be set and is skipped. Refer to the Document Editor: Basics 
User Guide for more information on range. 
skpiffld contains the name of the field that will appear in the Field Properties sheet, Skip if field. 
fillinruns is an auxiliary data structure that the user may attach to the XString that describes the fill- 
in rule for the field. A font run describes the subsequence of characters within an XString that share 
the same font attributes. 
Font Runs 
fillinruns is a pointer todp fontruns, a structure that permits the user to associate font properties with 


text. XString provides no facilities for associating font properties with text, therefore DoclCProps has been 
designed to permit the user to create various font information structures that point into XString 
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structures. It is also possible to enumerate the font runs in a given XString body of text by a call to 
dp _enumfrun, but doing so requires that you know where the font runs are located or declare them 
yourself. 


The data structures described here are used to mark font runs. A font run is defined as consecutive text 
characters sharing the same font. The members of dp fontruns describe an array of font runs and an 
integer value that specifies the length of the array. dp _fontru ns contains the following members: 


unsigned short length; 
dp run *runs; 


dp__fontruns points to dp _ run, which is a structure containing an array of runs. dp_run is called to 
specify the beginning of a font run. dp_runcontains the following members: 


dp fontprops props; 
unsigned index; 


props is the field describing the font used in the font run. index is the offset, specified in bytes, of 
the desired text within an array. A run is specified as the byte offset from the beginning of the byte 
array, as defined by index, to the byte after the byte run. For example: 


XString = ”"ABCDEFGH” (2*8 = 16 bytes) 
fontprops of ABC is font1 


fontprops of DE is font2 
fontprops of FGH is font3 


thus: 
length will be 3 
runs[0].props will be font1l 
runs[0].index will be 6 -- 3 characters (from 1 to 6) 
runs[1].props will be font2 
runs[1].index willbe 10 = -- 2 characters (from 7 to 10) 
runs[2].props will be font3 
runs[2].index willbe 16 —_-- 3 characters (from 11 to 16) 


Footnote Numbering Properties 


The chief type in this section isthe dp fnnumprops, which describes the properties that affect numbering 
within a footnote. dp__fnnumprops contains the following members: 


dp numctri numctrl; 
dp bool resteachpage; 
dp bool deferframes; 
dp bool rulingline; 

dp bool split; 

dp rulelen rulelen; 

dp indexrep indexrep; 
dp lang letters; 

dp replesent digits; 
unsigned int otherrule ; 
XString continuation ; 
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XString continued ; 


numctrl is the value of dp _numctrl, an enumerated type that controls footnote numbering across 
documents during pagination of a book or shared book. dp_numctrl may have one of the following 
values: 


/* restart */ 
/* continue */ 


NC_REST 
NC CONT 


resteachpage is a Boolean value that determines whether the numbering of footnotes is to be set back 
to 1 for each new page or if footnote numbering is to continue in numeric sequence for all the pages in 
the document. 

deferframes specifies whether the the body of text accompanying each footnote is to be placed on the 
same page as the corresponding footnote, or deferred so that all the footnote text bodies are placed at 
the end of the document. 

rulingline specifies whether a ruling line is to be created. 


split specifies whether split footnotes are to be created. 


rulelen specifies the length of the ruling line. This option is enabled when the value of of rulingline is 
set to TRUE. 


indexrep specifies the type of reference symbol to be used. It contains the following members and may 
have the corresponding values: 


IR INTEGER /* integer */ 
IR UPLETTER /* upper case letter */ 
IR LOWLETTER /* lower case letter */ 
IR DAGGERS /* daggers */ 


letters specifies the alphabet to be used, based upon nationality. It may have one of the following 
values: 


LANG USE /* USEnglish */ 

LANG UKE /* UKEnglish */ 
LANG FRN /* French */ 

LANG GMN /* German */ 

LANG SWD /* Swedish */ 

LANG ITA /* Italian */ 

LANG DUT /* Dutch */ 

LANG DAN /* Danish */ 

LANG NOR /* Norwegian */ 
LANG FIN /* Finnish */ 

LANG SPN /* Spanish */ 

LANG POR /* Portuguese */ 
LANG JPN /* Japanese */ 

LANG FRCAN /* FrenchCanadian */ 
LANG ENCAN /* EnglishCanadian */ 


digits specifies the manner in which numbers are displayed, based upon the respective numbering 
system. It may have the following value: 


RP ASCII /* ASCII */ 
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dp__fontprops is the chief type with respect to fonts. dp__fontprops contains the following members: 


dp fontdesc fontdesc; 
unsigned udlines; 

dp bool stkout; 

dp place place; 

dp bool tobedel; 

dp bool revised; 

dp width width: 
XString stylename; 

dp fontelmarr ntrelm; 
dp bool tranpare; 

dp color txtcol; 

dp _color hicol; 


The section titled dp__fontdesc describes the fontdesc field; the section titled dp__props describes the 


other fields inadp__fontprops. 


dp_fontdesc 


dp__fontdesc contains the following members: 


dp_family family; 


dp dvariant dvariant; 


dp weight weight; 
unsigned short size; 


family specifies the font that is to be used. It may have one of the following values: 


FMY CENT 
FMY FRUT 
FMY TITAN 
FMY PICA 
FMY TROJAN 
FMY VINTAGE 
FMY ELITE 
FMY LETTER 
FMY MASTER 
FMY CUBIC 
FMY ROMAN 
FMY SCIENT 
FMY GOTHIC 
FMY BOLD 
FMY OCRB 
FMY SPOKES 
FMY XEROX 
FMY CENTTHIN 
FMY SCIENTTHIN 
FMY HELV 
FMY HELVCOND 
FMY OPTIMA 
FMY TIMES 
FMY BASK 
FMY SPARTAN 
FMY BODONI 


/* century (also, classic)*/ 
/* frutiger (also, modern) */ 
/* titan */ 

/* pica */ 

/* trojan */ 

/* vintage */ 

/* elite */ 

/* letter gothic */ 

/* master */ 

/* cubic */ 

/* roman */ 

/* scientific */ 

/* gothic */ 

/* bold */ 

/* ocrB */ 

/* spokesman */ 

/* xerox logo */ 

/* century thin */ 

/* scientific thin */ 

/* helvetica */ 

/* helvetica condensed */ 
/* optima */ 

/* times */ 

/* baskerville */ 

/* spartan */ 

/* bodoni */ 
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FMY PALATINO 
FMY CALEDONIA 
FMY MEMPHIS 
FMY EXCELSIOR 
FMY OLYMPIAN 
FMY UNIVERS 
FMY UNIVERSCOND 
FMY TREND 
FMY BOXPS 
FMY TERMINAL 
FMY OCRA 

FMY LOGO1 
FMY LOGO2 
FMY LOGO3 
FMY GENEVA2 
FMY TIMES2 
FMY SQUARE3 
FMY COURIER 
FMY FUTURA 
FMY PRESTIGE 
FMY ALLGOTHIC 
FMY SCH BOOK 


/* palatino */ 

/* caledonia */ 

/* memphis */ 

/* excelsior */ 

/* olympian */ 

/* univers */ 

/* univers condensed */ 
/* trend */ 

/* boxPS */ 

/* terminal */ 

/* ocrA */ 

/* logo! */ 

/* logo2 */ 

/* logo3 */ 

/* geneva2 */ 

/* times2 */ 

/* square3 */ 

/* courier */ 

/* futura */ 

/* prestige */ 

/* alLetterGothic */ 
/* century school book */ 


dvariant specifies the manner in which numeric characters are displayed, such as roman or italic. 
It may have one of the following values: 


DV ROMAN 
DV_ITALIC 


/* roman */ 
/* italic */ 


weight specifies the intensity at which characters are displayed. It may have one of the following 


values: 


WT MEDIUM 
WT_ BOLD 


/* medium */ 
/* bold */ 


size is the size of the font. This value may be anywhere within the range of 0 to 1023, inclusive. 


Other fieldsindp_fontprops 


udlines specifies the number of times that the character is to be underlined. Acceptable values range 


between 0 to 2, inclusive. 


stkout specifies whether or not the character is to be struck horizontally through the middle. 


place specifies the position of the character relative to the line. It may have one of the following 


values: 


PL NULL 
PL SUB 

PL SUBSUB 
PL SUBSUP 
PL SUP 

PL SUPSUB 
PL__SUPSUP 


/* null */ 

/* subscript */ 

/* sub subscript */ 

/* sub superscript */ 
/* superscript */ 

/* super subscript */ 
/* super superscript */ 


tobedel indicates that text has been marked for deletion in the Redlining mode. 
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revised indicates text that was typed while Redlining was enabled but was left unfinalized. 


width specifies the spacing between characters in the Japanese character set. It may have one of the 
following values: 


WD PROP /* proportional */ 
WD QUARTER /* quarter */ 

WD THIRD /* third */ 

WD HALF /* half */ 

WD THREEQUART /* three quarter */ 
WD FULL /* full */ 


Normal spacing is achieved by specifying WD__ PROP. 
stylename is a text string that specifies the name of the style sheet. 
ntrelm specifies the neutral elements of a style property. 


dp_fontelmarr controls subtle aspects of the text appearance. dp__fontelmarr is an array of dp__bool 
and may contain the following elements: 


FE FAMILY /* family */ 

FE DSGNVAR /* design variant */ 
FE WEIGHT /* weight */ 

FE PSIZE /* point size */ 

FE UDLINES /* n underlines */ 
FE STKOUT /* strikeout */ 

F PLACE /* placement */ 
FE TOBEDEL /* to be deleted */ 
FE REVISED /* revised */ 

FE WIDTH /* width */ 

FE TXTCOL /* text color */ 

FE HLCOL /* highlight color */ 


An example of an array declaration is: 
typedefdp_ booldp _fontelmarr[FE_HLCOL + 1]; 


The size of the preceding array is 12 ((FE_HLCOL = 11) +1), where FE_ FAMILY is the first 
element and has a value of 0. 


tranpare is a Boolean value that specifies whether the text will be displayed as a solid object or, if the 
text is placed over another object, the object in the background will show through the text. 


txtcol and hlcol specify the color attributes of a text string. txtcol indicates the color of text which isn't 
highlighted. hlcol indicates the color of text which is highlighted. Any valid color may be specified. 


Frame Properties 


The chief type in this section is dp__frameprops. It specifies the properties to be attributed to an anchored 
frame. dp _frameprops contains the following members: 


dp borderstyle bdstyle; 
unsigned bdthick; 

dp framedims frdims; 
dp bool fxw; 

dp _bool fxh; 
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dp spanspan; 

dp valignment valign; 
dp halignment halign; 
unsigned short tmgn; 
unsigned short bmgn: 
unsigned short Imgn; 
unsigned short rmgn; 
dp pagenumber pnum; 
dp bool tranpare; 

dp color bdcol; 

dp _color bgcol; 


bdstyle specifies the display characteristics of the lines comprising the frame border. It may have one 
of the following values: 


BDS INVISIBLE /* invisible */ 
BDS SOLID /* solid */ 
BDS DASHED /* dashed */ 
BDS BROKEN /* broken */ 
BDS DOTTED /* dotted */ 
BDS DOUBLE /* double */ 


bdthick specifies the thickness of the frame border. This value is specified as an integer in units of 
points. A point is 1/72 inch. 


bdthick is affected by the value of bdstyle. If bdstyle is set to BDS DOUBLE, then bdthick may range 
from between 3 to 18, inclusive, in multiples of 3 points. The remaining values of bdstyles may have a 
bdthick value ranging from 1 to 6 points, inclusive. 


frdims specifies the height and width of the frame. These dimensions are also in units of points, where 
one point is equivalent to 1/72 inch. dp__framedims contains the following members: 


unsigned w; 
unsigned h; 


w is the width of the frame along the x axis. y is the height of the frame along the y axis. 
fxw and fxh are Boolean values that, when set to TRUE, indicate whether the frame will expand when 
necessary and the direction of expansion. fxw permits expansion in a horizontal direction along the x 


axis. fxh permits expansion in a vertical direction along the y axis. 


span specifies the amount of space the frame may occupy with respect to the page. dp_span may have 
one of the following values: 


SP__FULCOLUMN /* full column */ 
SP__FULPAGE /* full page */ 


valign and halign are the values ofdp__valignmentanddp _halignment, respectively. They are used to 
control the alignment of the frame relative to the top and bottom edges of the page. 


dp _valignment may have one of the following values: 


VA_ TOP /* top */ 
VA_ BOTTOM /* bottom */ 
VA_ FLOATING /* floating */ 
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dp_halignment can have any of the following values: 


HA_ LEFT /* left */ 
HA CENTERED /* centered */ 
HA RIGHT /* right */ 


tmgn, bmgn, Imgn, and rmgn are the margins of the frame, expressed as points. One point is the 
equivalent of 1/72 inch. 


pnum indicates the page number where the corresponding anchored frame resides. dp__pagenumber 
contains the following members: 


unsigned relpn; 
unsigned dispn; 


relpn is the page number of the document, relative to the first page which resides at the start of the 
document. dispn is the property of the page format character which controls the display of page 
numbers. 


Index Properties 


The chief type in this section is dp__indexprops. It describes the properties of the Index option. 
dp_indexprops contains the following members: 


dp indexhdl sphdi; 
dp bool useclass; 
dp bool usealter; 
XString class; 
XString alter; 


sphdl is the value of dp_indexhdl, an enumerated type that specifies the special handling that the 
index is to receive. This has the same effect as the Special Handling field in the Index Object Property 
Sheet. sphdl may have one of the following values: 


IDX__UNIT /* index as a unit */ 
IDX_IGNORE /* ignore */ 
IDX__ CLASSIFY /* classify alike */ 


useclass is a Boolean value that indicates whether or not a classification is to be used. This has the 
same effect as the Use Classification field in the Index Object Property Sheet. A value of TRUE 
indicates that a classification is desired. 


usealter is a Boolean value that specifies whether or not an alternate is to be used. This has the same 
effect as the Use Alternate Term field in the Index Object Property Sheet. 


Page Properties 


The chief type in this section is dp__pageprops, a structure that describes the various properties to be 
associated with a VP document page. dp__pageprops contains the following members: 


/* layout properties */ 
dp pagedims dims; 
unsigned short tmgn; 
unsigned short bmgn; 
unsigned short Imgn; 
unsigned short rmgn; 
dp__pagesidestpagside; 


DOCUMENT INTERFACES TOOLKIT SYSTEM REFERENCE 2-9 


DOCUMENT IC PROPERTY LIBRARY 


2-10 


unsigned bindwidth; 

/* column structure properties */ 
unsigned ncol; 
dp _ bool bicol; 
dp bool uneqcol; 
unsigned short colsp; 
dp colwidths *colwidths; 
dp coldirct coldirct; 

/* heading & footing properties */ 
dp hdfttype hdfttype; 
dp bool hdthispage; 
dp bool hdsamepage; 
dp bool ftthispage; 
dp bool ftsamepage; 
dp horpos hdpos; 
dp horpos ftpos; 

/* page numbering properties */ 
dp pntype pagnumtype; 
dp verpos vnum; 
dp horpos hnum; 
unsigned stpagnum; 


dims is the value of dp _pagedims, a structure that specifies the width and height of a document page 
in units of 1/72 inch. dp __pagedims contains the following members: 


unsigned short w; 
unsigned short h; 


tmgn, bmgn, Imgn, and rmgn are integers that specify the page margins in units of 1/72 inch. 
stpagside is the value ofdp__pageside, an enumerated type that specifies whether or not the first, or 


starting, page of the document should be on the left-hand side or the right-hand side. dp__pageside 
may have one of the following values: 


PS_NIL /* nil */ 
PS LEFT /* left */ 
PS__RIGHT /* right * 


PS__NIL indicates that there is no difference between the left- and right-hand sides of a document. 


bindwidth is the additional amount of space to remain on the left edge of the completed document to 
account for the space necessary during book binding. 


ncol, bicol, uneqcol, and colsp determine column structure. ncol is an integer that specifies the 
number of columns per page. A maximum of 50 columns may be specified. blcol is a Boolean value that 
specifies whether the length of the column will be equal to the length of the page. uneqcol is a Boolean 
value that specifies whether the columns may have varying widths. colsp is the amount of space 
between columns, specified in units of 1/72 inch. 


colwidths is a pointer to dp_colwidths, a structure that specifies the width of each column in a 
document. It contains the following members: | 


unsigned length; 
dp_colwidth *widths; 
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length is an integer that specifies the number of columns. widths is a pointer todp__colwidth, an 
integer that specifies the width of each column. The value of widths is specified in units of 1/72 
inch. dp __colwidth contains the following member: 


unsigned short w; 


coldirct is the value of dp_coldirct, an enumerated type that specifies the direction of each column. It 
may have one of the following values: 


cD_LR /* left to right */ 
CD_ RL /* right to left */ 


hdfttype is the value ofdp__hdfttype, an enumerated type that specifies how headings and footings in 
the PFC are to be propagated across pages. It may have one of the following values: 


HFT NONE /* none */ 
HFT CONT /* continue */ 
HFT RESET /* reset */ 


The preceding are the same as those shown for Page Numbering in the Page Format Property 
Sheet and they accept the same values. 


hdthispage is a Boolean value that determines whether the header is to be displayed on the current 
page or on the succeeding page. Page headers are enabled when a numbering pattern has been toggled 
in the PFC so that it is active and it's set to appear in the top margin. When the numbering pattern is 
active but set to appear on the bottom margin, hdthispage will have no effect. 

ftthispage acts like hdthispage with respect to footers. See the previous paragraph. 


hdsamepage is a Boolean value that determines whether the headers used on both the left and right 
pages will be identical. 


ftsamepage acts like hdsamepage with respect to footers. See the previous paragraph. 


hdpos and ftpos control the horizontal positioning of headers and footers, respectively. They may have 
one of the following values: 


HP LEFT /* left */ 

HP RIGHT /* right */ 

HP CENTERED /* centered */ 

HP OUTER /* outer of page */ 


pagnumtype is the value of dp pntype, an enumerated type that specifies the the type of 
PageNumbering to be used. It may have one of the following values: 


PNT NONE /* none */ 

PNT CONTNUM /* continue only page number */ 
PNT CONTNUMANDPAT /* continue number and pattern */ 
PNT RESTART /* restart */ 


vnum and hnum are the values of dp_verpos and dp_horpos, respectively. They control the vertical 
and horizontal positioning of PageNumbering in the document. vnum may have one of the following 


values: 
VP__TOP /* top edge */ 
VP__ BOTTOM /* bottom edge */ 
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hnum may have one of the following values: 


HP LEFT /* left edge*/ 

HP RIGHT /* right edge*/ 

HP CENTERED /* center of page*/ 

HP OUTER /* left edge on left pages and right edge on right pages*/ 


stpagnum is an integer value that specifies the page number to be assigned the starting page. All 
succeeding pages will incremented accordingly. 


Informat, and Inloc are currently not implemented. 


Paragraph Properties 


The chief type in this section isdp paraprops. It is a structure that specifies the properties of paragraphs 


2-12 


in the document It contains the following members: 


dp basprops basprops; 
dp tabstops tabstops; 

XString stylename; 

dp _paraelmarr ntrelm; 


basprops is the value of dp basprops, a structure that specifies the standard properties associated 
with every paragraph, such as justification, indentation, and language. These are the same properties 
that appear on the Paragraph property sheet. Refer to the section titled dp ‘*intro for more 
information ondp__basprops. — 

tabstops is the value of dp tabstops, a structure that specifies the tab stops associated with 
paragraphs. These are the same properties that appear on the Tab Settings property sheet. Refer to 
sections titled Basic Property Records and Tabs for more information ondp__tabstops. 


stylename is a text string that specifies the style name of paragraph property. 


ntrelm is the value ofdp paraelmarr, an array of dp__bool that describes basic, or default, paragraph 
style properties. It is declared as follows: 


typedefdp booldp_paraelmarr[PE_TABSTOPS + 1]; 


Individual elements may be assigned the following values: 


PE PRELEAD /* pre leading */ 

PE POSLEAD /* post leading */ 

PE LINDENT /* left indent */ 

PE RINDENT /* right indent */ 

PE LNH /* line height */ 

PE PARALIGN /* para alignment */ 

PE JUST /* justified */ 

PE HYPH /* hyphenated */ 

PE KPNEXT /* keep with next para */ 

PE LANG /* language */ 

PE STRSUC /* streak succession */ 

PE DEFTABLEAD /* default tab stop dot leader */ 
PE DEFTABJUST /* default tab stop justified */ 
PE DEFTABOFFSET /* default tab stop offset */ 

PE DEFTABALIGN /* default tab stop alignment */ 
PE TABSTOPS /* tab stops*/ 
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Basic Property Records 
dp __basprops contains the following members: 


unsigned short prelead; 
unsigned short poslead; 
unsigned short lindent; 
unsigned short rindent; 
unsigned short Inh; 

dp _paralign paralign; 
dp bool just; 

dp bool hyph; 

dp bool kpnext; 

dp lang lang; 

dp strsuc strsuc; 

dp deftabsp deftabsp; 
dp__tabalign deftabal; 


prelead and postlead are integers that specify the amount of space that is to precede and follow 
the paragraph, respectively. These values are specified in units of points, where 1 point is the 
equivalent to 1/72 inch. 


lindent and rindent are integers that specify the amount of space that is to comprise the margins 
on the left and right sides of the paragraph, respectively. These values are specified in units of 
points, where 1 point is the equivalent to 1/72 inch. 


Inh is an integer that specifies the height of lines comprising a paragraph. These values are 
specified in units of points, where 1 point is the equivalent to 1/72 inch. 


paralign is the value of dp__paralign, an enumerated type that specifies how the paragraph is to be 
aligned relative to the containing text column or text block. It may have one of the following 


values: 
PA_ LEFT /* left */ 
PA_CENTER /* center */ 
PA RIGHT /* right */ 


just is a Boolean value that specifies whether the lines of text in paragraphs will be stretched to 
make the left and right edges consistently even. That is, the line will be justified. A value of FALSE 
will result in a ragged right edge. 


hyph is a Boolean value that specifies whether words on the right side of a line that are too long to 
fit entirely on the one line should be hyphenated to facilitate justification. If justification is not 
enabled, this property will be ignored. 


kpnext is a Boolean value that specifies whether, during pagination, the current paragraph is to 
be kept on the same page as the following paragraph. 


lang is the value of dp lang, an enumerated type that specifies the type of text characters that 
will be used in the paragraphs. The specified language is used in formatting decimal tabs, 
hyphenation, spell checking, and so. It may have one of the following values: 


LANG USE /* USEnglish */ 
LANG UKE /* UKEnglish */ 
LANG FRN /* French */ 
LANG GMN /* German */ 
LANG SWD /* Swedish */ 
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Tabs 


LANG ITA /* Italian */ 

LANG DUT /* Dutch */ 

LANG DAN /* Danish */ 

LANG NOR /* Norwegian */ 
LANG FIN /* Finnish */ 

LANG SPN /* Spanish */ 

LANG POR /* Portuguese */ 
LANG JPN /* Japanese */ 

LANG FRCAN /* FrenchCanadian */ 
LANG ENCAN /* EnglishCanadian */ 


strsuc is the value of of the type dp__strsuc, an enumerated type that specifies whether text 
characters should be generated within paragraphs from left to right (e.g. English) or right to left 
(e.g. Hebrew). dp__strsuc may have one of the following values: 


SS__LR /* left to right */ 
SS__RL /* right to left */ 


deftabsp is the value of of the type dp__deftabsp, an unsigned number that specifies the default 
number of spaces between tab stops. The value is specified in units of points, where there 1 point is 
equal to 1/72 of an inch. 


deftabal is the value of of the type dp tabalign, an enumerated type that specifies the manner in 
which tabs are aligned relative to the left paragraph margin, the center of the paragraph, the right 
paragraph margin, or points. A point is the equivalent of 1/72 of an inch. dp tabalign may have 
one of the following values: a 


TSA LEFT /* left */ 
TSA CENTER /* center */ 
TSA RIGHT /* right */ 
TSA__DECIMAL /* decimal */ 


dp__tabstop is an array of structures whose members specify the tab settings of the current paragraph. 
It contains the following members: 


dp_bool dotld; 

dp_bool eqsp; 

dp_taboffset offset; 

dp_tabalign align; 

dotlid is a Boolean value that specifies whether the tab will have leader dots. 


eqsp is a Boolean value that specifies whether tabs will be equally spaced. 


offset is the value of of the type dp taboffset, an unsigned number that specifies the location of 
each tab stop, relative to the margin. 
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align is the value of the type dp _ tabalign, an enumerated type that specifies the manner in which 
tabs are aligned relative to the left paragraph margin, the center of the paragraph, the right 
paragraph margin, or points. A point is the equivalent of 1/72 of an inch. dp tabalign may have 
one of the following values: _ 


TSA LEFT /* left */ 
TSA CENTER /* center */ 
TSA RIGHT /* right */ 
TSA DECIMAL /* decimal */ 


An array of tabstops used to create or modify an object in a document must be sorted by increasing 
order of offsets. An offset that is equal to the previous one is ignored. During enumeration, 
tabstop arrays passed to the user will always be sorted in this manner. The maximum number of 
tabstops that may be set in a paragraph is 100. 


Document Mode Properties 


Mode properties affect the auxiliary menus of a VP document. The key mode property isdp _modeprops. It 
contains the following members: 


dp bool strct; 

dp bool nonprint; 
dp bool cover; 
dp bool prompt; 


strct, nonprint, cover, and prompt are Boolean values that specify the manner in which the document 
will be displayed. If set to TRUE, the document will display structure and non-printing characters, the 
cover sheet, and prompt fields, respectively. 


dp__modesel specifies the dp__modeelm of a document to be manipulated. dp__modesel is an array of 
dp__bool and is declared as follows: 


typedefdp_ booldp modesel[ME_ PROMPT + 1]; 


dp __modee!m is an enumerated type that may have one of the following values: 


ME_STRCT /* structure showing */ 
ME __NONPRINT /* non printing showing */ 
ME COVE /* cover sheet showing */ 
ME PROMPT /* prompt fields */ 

Font Style Properties 


The chief type in this section is dp__fstyleprops, a structure that specifies font style properties. 
dp_fstyleprops contains the following members: 


dp fontprops props; 
XString desc; 

unsigned short softpos; 
unsigned short stylepos; 


props and desc are the properties of the font style. 
softpos is the position of the SoftKey used to invoke the stylesheet. stylepos is the position at which 


the stylesheet propertysheet is to appear on the Style Softkey Assignment Sheet. Please refer to the 
figure on the following page for more information on StyleSheet and Style SoftKey. 
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Paragraph Style Properties 
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The chief type in this section is dp__pstyleprops, a structure whose members specify the paragraph style 
properties. dp__pstyleprops contains the following members: 


dp paraprops props; 
XString desc; 

unsigned short softpos; 
unsigned short stylepos; 


props and desc are the properties of the paragraph style. 
softpos is the position of the SoftKey used to invoke the StyleSheet. stylepos is the position of the 


propertysheet of stylesheet. Please refer to the figure on the following page for more information on 
StyleSheet and Style SoftKey. 
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Style SoftKey position from left to right of 1st row corresponds to 1, 2...6, 7. 
2nd row corresponds to 8, 9...13, 14. 3rd row... 
For example. softpos of Font 1 is 9. softpo of Font 2 is 17. softpos of Para 0 is 33. 


Position of StyleSheet and Style SoftKey 


TextFrame Properties 


The chief type in this section is dp tframeprops, a structure whose members specify the text frame 
properties. dp _tframeprops contains the following members: 


XString name; 
unsigned innermargin; 
dp orient orientation; 
dp bool lastlinejust; 
dp__boolautohyphen; 
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name is a text string that specifies the name of the text frame. innermargin is an unsigned number 
that specifies the amount of space to be allocated for the inner margin of all four edges of the frame. 
innermargin is specified in units of micas. 


Orientation is the value of dp__ orient, an enumerated type that specifies the manner in which text is 
placed in the frame. Text may flow either horizontally (e.g., English) or vertically (e.g., Japanese). 


dp orient can have any of the following values: 


OR_HOR /* horizontal */ 
OR_ VER /* vertical */ 


Only Japanese text may flow vertically. 


lastlinejust is a Boolean value that, when set to TRUE, is used to specify whether the last line of text in 
linked text frames is to be justified. 


autohyphen is a Boolean value that, when set to TRUE, is used to specify whether the last line of text 
in linked text frames is to be automatically hyphenated. 


Color Properties 


2-18 


The chief type in this section is the dp__color, which describes the color properties. dp__color contains the 


following members: 
int y; I*Q<=y< = 10000 */ 
inte; /* -10000 <= e< = 10000 */ 
ints; /* -10000 <=s < = 10000 */ 


The color is specified the combination of y, e and s, for example, black is specified as {0, 0, 0} and white 
is specified as {10000, 0, 0}. Refer to the Xerox Color Encoding Standard for more details. 


dp__colorname is the name of the well known color which may have one of the following values: 


CL WHITE /* white */ 

CL BLACK /* black */ 

CL PINK /* pink */ 

CL RED /* red * 

CL LGREEN /* light green */ 

CL GREEN /* green */ 

CL LBLUE /* light blue */ 

CL BLUE /* blue */ 

CL YELLOW /* yellow */ 

CL GOLD | /* gold */ 

CL LORANGE /* light orange */ 

CL ORANGE /* orange */ 

CL VIOLET /* violet */ 

CL PURPLE /* purple */ 

CL TAN /* tan */ 

CL BROWN /* brown */ 

CL LGRAY /* light gray */ 

CL MGRAY /* medium gray */ 

CL DGRAY /* dark gray */ 

CL PGYELLOW /* pale green yellow */ 
CL LBYELLOW /* light brilliant yellow */ 
CL MYELLOW /* moderate yellow */ 
CL SYELLOW /* strong yellow */ 

CL PYELLOW /* pale yellow */ 
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CL BYELLOW 


CL MOYELLOW 


CL SOYELLOW 
CL LOYELLOW 


CL DOYELLOW 


CL LGYELLOW 
CL GYELLOW 
CL POYELLOW 
CL SORANGE 
CL MORANGE 
CL SRORANGE 


CL MRORANGE 


CL DRORANGE 
CL VSRED 

CL BRED 

CL MRED 

CL DAPRED 
CL SRED 

CL MPRED 
CL SPRED 

CL DRED 

CL DEPRED 
CL VPRED 

CL LYELLOW 
CL MYPINK 
CL PPPINK 
CL DAPPINK 
CL LPPINK 
CL DEPPINK 
CL MPPINK 
CL GPPINK 
CL PPINK 

CL LRPURPLE 
CL VRPURPLE 
CL MRPURPLE 
CL SRPURPLE 
CL DVIOLET 
CL MVIOLET 
CL SVIOLET 
CL DAPBLUE 
CL VPPBLUE 
CL LPBLUE 
CL SBLUE 

CL DEBLUE 
CL DEPBLUE 
CL VLBLUE 
CL BBLUE 

CL DSBLUE 
CL DABLUE 
CL VPBLUE 
CL VBLUE 

CL DVBLUE 
CL MBLUE 
CL VLGBLUE 
CL BGBLUE 
CL SGBLUE 
CL VGBLUE 
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/* brilliant yellow */ 

/* moderate orange yellow */ 
/* strong orange yellow */ 
/* light orange yellow */ 

/* deep orange yellow */ 

/* light greenish yellow */ 
/* grayish yellow */ 

/* pale orange yellow */ 

/* strong orange */ 

/* moderate orange */ 

/* strong reddish orange */ 
/* moderate reddish orange */ 
/* dark reddish orange */ 

/* very strong red */ 

/* brilliant red */ 

/* moderate red */ 

/* dark purplish red */ 

/* strong red */ 

/* moderate purplish red */ 
/* strong purplish red */ 

/* dark red */ 

/* deep purplish red */ 

/* vivid purplish red */ 

/* light yellow */ 

/* moderate yellow pink */ 
/* pale purplish pink */ 

/* dark purplish pink */ 

/* light purplish pink */ 

/* deep purplish pink */ 

/* moderate purplish pink */ 
/* grayish purplish pink */ 
/* pale pink */ 

/* light reddish purple */ 

/* vivid reddish purple */ 

/* moderate reddish purple */ 
/* strong reddish purple */ 
/* deep violet */ 

/* moderate violet */ 

/* strong violet */ 

/* dark purplish blue */ 

/* very pale purplish blue */ 
/* light purplish blue */ 

/* strong blue */ 

/* deep blue */ 

/* deep purplish blue */ 

/* very light blue */ 

/* brilliant blue */ 

/* deep strong blue */ 

/* dark blue */ 

/* very pale blue */ 

/* vivid blue */ 

/* deep vivid blue */ 

/* moderate blue */ 

/* very light greenish blue */ 
/* brilliant greenish blue */ 
/* strong greenish blue */ 
/* vivid greenish blue */ 
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CL DGBLUE /* deep greenish blue */ 

CL VLGREEN /* very light green */ 

CL MBGREEN /* moderate bluish green */ 
CL SBGREEN /* strong bluish green */ 

CL DEBGREEN /* deep bluish green */ 

CL DABGREEN /* dark bluish green */ 

CL VPYGREEN /* very pale yellow green */ 
CL MGREEN /* moderate green */ 

CL DGREEN /* deep green */ 

CL BYGREEN /* brilliant yellow green */ 
CL VYGREEN | /* vivid yellow green */ 

CL SYGREEN /* strong yellow green */ 
CL DYGREEN /* deep yellow green */ 

CL VPGREEN /* very pale green */ 

CL PYGREEN /* pale yellow green */ 

CL MBROWN /* moderate brown */ 

CL MRBROWN /* moderate reddish brown */ 
CL YWHITE /* yellowish white */ 

CL YGRAY /* yellowish gray */ 

CL PWHITE /* purplish white */ 

CL BWHITE /* bluish white */ 

CL LBGRAY /* light bluish gray */ 

CL BGRAY /* bluish gray */ 

CL DBGRAY /* dark blueish gray */ 

CL BBLACK /* bluish black */ 

CL VLGRAY /* very light gray */ 


CL_VDGRAY /* very dark gray */ 
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dp__*col* 


NAME 


dp__colfromname,dp__namefromcol,dp__wkcolfromcol - color property 


SYNOPSIS 
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#include “DociCProps.h” 


int 
dp colfromname(name, ret) 
dp_colorname name; 
ret wkcolfromname ‘ret; /* Returned */ 


int 
dp namefromcol(color, ret) 
dp color *color; 
ret namefromwkcol *ret; /* Returned */ 


int 
dp_wkcolfromcol(color, ret) 
dp__color *color; 
ret wkcolfromcol *ret; /* Returned */ 


DESCRIPTION 


Thedp_ colfromname() function is used to retrieve the integer equivalent of a well known color. The name 
argument is an integer value that specifies the name of the color. This function returns ret, a structure 
whose one member, dp__color, is an array of three integers that specifies the desired color. ret may then 
be passed as an argument to those functions that require color information. 


Thedp namefromcol() function is used to retrieve the name of a color by supplying the data that defines 
the well known color. The color argument is a pointer to a structure whose three members define the color 
in question. This function returns ret, a structure containing the name of the color. 


Thedp wkcolfromcol() function is used to retrieve a well known color from color. The color argument is a 
pointer to dp color, a structure whose three members define that color. This function returns ret, a 


structure whose one member, dp_ color, contains the integer data defining the well known color . 


dp__color contains the following members: 


int y; *0 <= y <= 10000 %*/ 
inte; /* -10000 < = e < = 10000 */ 
ints; /* -10000 < = s < = 10000 */ 


color is specified as a combination of y, e and s. The number to color relationship is defined by the BWS 
framework. It is recommended that the user does not set the y, e, and s values directly. For example, 
black is specified as {0, 0, 0} and white is specified as {10000, 0, 0}. Note that dp color may also be 
aliased by using dp __yes. _ 


Refertodp intro at the beginning of this section for more information regarding colors. 
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RETURN VALUE 


If the call is successful 0 is returned, otherwise -1 is returned. The function getsigno() is used to get the 
reason for the failure. 


ERRORS 


dp_*col() will fail if one or more of the following are true: 
Doc BadParm One of the arguments specified is invalid. 
Doc_IllegalHandle The specified handle is illegal. 


Doc TimeOut Inter-process communication has exceeded the maximum allowed time. 
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dp__enumfrun 


NAME 


dp__enumfrun - enumerate font run 
SYNOPSIS 


#include “DociCProps.h” 
#include “XString.h” 


int 
dp enumfrun(r, runs, proc, cdat,ret) 
String r; : 
dp fontruns *runs; 
dp frunproc *proc; 
void *cdat; /* NULL */ 
dp_ bool *ret; /* Returned */ 


CALLBACK PROCEDURE 
dp_bool 
dp_frunproc(r, props, cdat) 
XString r; 
dp fontprops *props; 
void *cdat; 
DESCRIPTION 
A font run is a way in which to associate font properties with text. The dp _enumfrun() function is used to 
enumerate user-defined fill-in runs, as defined in dp__fldprops. This 1s achieved by creating font 
information structures that point into associated XString structures. 


The r argument is the text string to be enumerated. It is the value of the fillin argument to dp__fldprops. 


The runs argument is a pointer todp__fontruns, a structure whose members contain font properties and an 
index. It is the value of the fillinruns argument todp_fldprops. 


The proc argument is a pointer todp frunproc, a user-defined callback procedure. Its usage is defined by 
the user. _ 


The cdat argument is user-defined data that is supplied to, and used by, dp__frunproc . Its usage is also 
defined by the user. 


Ifdp__frunproc() returns TRUE, the enumeration stops and ret returns TRUE. 
RETURN VALUE 


If the call is successful 0 is returned, otherwise -1 is returned. The function getsigno() is used to get the 
reason for the failure. 
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ERRORS 
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dp _enumfru n() will fail if one or more of the following are true: 
Doc BadParm One of the arguments specified is invalid. 
Doc_IllegalHandle The specified handle is illegal. 


Doc TimeOut Inter-process communication has exceeded the maximum allowed time. 
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dp__get*def 
NAME 

dp_get*def - get default values of properties 
SYNOPSIS 


#include “DociCProps.h” 


int | 
dp __getbreakdef(props) 

dp__breakprops “props; /* Returned */ 
int 
dp __getfielddef(props) 

dp__fldprops *props; /* Returned */ 
int 
dp _getfnnumdef(props) 

dp__fnnumprops *props; /* Returned */ 
int 
dp _getfontdef(props) 

dp__fontprops *props; /* Returned */ 
int 
dp _getfontdescdef(desc) 

dp__fontdesc *desc; /* Returned */ 
int 
dp _getrundef(run) 

dp_run *run; /* Returned */ 
int 
dp_getframedef(props) 

dp_frameprops *props; /* Returned */ 
int 
dp __getindexdef(props) 

dp_indexprops *props; /* Returned */ 
int 
dp __getpagedef(props) 

dp __pageprops “props; /* Returned */ 
int 
dp _getcolwidthdef(width) 

dp_colwidth *width; /* Returned */ 
int | 
dp __getparadef(props) 

dp_paraprops *props; /* Returned */ 
int 


dp _getbaspropsdef(props) 
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dp__basprops *props; /* Returned */ 
int 
dp__gettabstopdef(stop) 

“dp __tabstop *stop; /* Returned */ 
int 
dp __getmodedef(props) 

“dp modeprops *props; /* Returned */ 
int 
dp__getfontstyledef(props) 

dp_fstyleprops “props; /* Returned */ 
int | 
dp__getparastyledef(props) 

“dp pstyleprops *props; /* Returned */ 
int 
dp__gettframedef(props) 

dp_tframeprops “props; /* Returned */ 
int 
dp__getfontelmarralltrue(ret) 

dp__fontelmarr ret; /* Returned */ 
int 
dp__getparaelmarralltrue(ret) 

“dp _ paraelmarr ret; /* Returned */ 
int 
dp _getpagedel (ret) 

ret__ getpagedel *ret; /* Returned */ 
int 
dp__gettoc(ret) 

ret__gettoc “ret; /* Returned */ 

DESCRIPTION 


The dp__get*def() functions are used to obtain declared constants so that property structures may be 
initialized with neutral property values. A part of the information is obtained from the system defined 
data. 


Before calling one of these functions, the user must declare a structure of the appropriate type and pass its 
address to thedp__get*def() function. 


dp__getbreakdef() gets the following default values for page break properties: 


dp__breaktype type; /* BR__NPAGE (new page) */ 
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dp __getfielddef() gets the following default values for field properties: 


dp_ lang lang; 
unsigned length; 

dp bool req; 

dp skpchoice skpif; 
dp bool stpskp; 

dp fldchoice type; 
XString fill-in; 
XString desc; 
XString format; 
XString name; 
XString range; 
XString skpiffid; 
dp__fontruns *fillinruns; 


/*LANG USE (USEnglish) */ 
xO*/ 

/* FALSE */ 

/* SKP NEVER */ 
/* FALSE */ 
/*FLD ANY */ 
/* NULL */ 

/* NULL */ 

/* NULL */ 

/* NULL */ 

/* NULL */ 

/* NULL */ 

/* NULL */ 


dp _getfnnumdef() gets the following default values for footnote numbering properties: 


dp numctrl numctrl; 
dp bool resteachpage; 
dp bool deferframes; 
dp bool rulingline; 

dp bool split; 

dp rulelen rulelen; 

dp indexrep indexrep; 
dp lang letters; 

dp replesent digits; 
unsigned int otherrule ; 
XString continuation ; 
XString continued ; 


/* NC REST (restart) */ 
/* FALSE */ 

/* FALSE */ 

/* FALSE */ 

/* FALSE */ 

/* RL ONETHIRD */ 
/*1IR INTEGER */ 

/* LANG USE (USEnglish) */ 
/* RP ASCII */ 

/* 144 */ 

/* NULL */ 

/* NULL */ 


dp__getfontdef() gets the following default values for font properties: 


dp fontdesc fontdesc; 
unsigned udlines; 

dp bool stkout; 

dp place place; 

dp bool tobedel:; 

dp bool revised; 

dp width width: 
XString stylename; 

dp fontelmarr ntrelm; 
dp bool tranpare; 

dp color txtcol; 

dp color hlicol; 


/*Q*/ 

/* FALSE */ 

/* PL NULL */ 
/* FALSE */ 

/* FALSE */ 

/* WD PROP (proportional) */ 
/* NULL */ 

/* all TRUE */ 
/* TRUE */ 

/* 0,0, 0 */ 

/* 10000, 0, 0 */ 


dp__getfontdescdef() gets the following default values for font description: 


dp family family; 

dp dvariant dvariant; 
dp weight weight; 
unsigned short size; 


/* FMY FRUT (modern) */ 
/*DV ROMAN */ 

/*\NT MEDIUM */ 

(* 12 %7 
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dp _getrundef() gets the following default values for font run: 


dp fontprops props; 
unsigned index; 


/* 0 */ 


dp__getframedef() gets the following default values anchored frame properties: 


dp bordarstyle bdstyle; 
unsigned bdthick; 

dp framedims frdims; 
dp bool fxw; 

dp bool fxh; 

dp span span; 

dp valignment valign; 
dp halignment halign; 
unsigned short tmgn; 
unsigned short bmgn; 
unsigned short Imgn; 
unsigned short rmgn; 
dp pagenumber pnum; 
dp bool tranpare; 

dp color bdcol; 

dp _color bgcol; 


/* BDS SOLID */ 
2%) 

/* 72,72 */ 

/* TRUE */ 

/* TRUE */ 

/* SP FULCOLUMN (full column) */ 
/*VA FLOATING */ 
/* HA CENTERED */ 
[* 1847 

/* 18 */ 

/*0*/ 

/*0*/ 

= 41,1 */ 

/* FALSE */ 

/* 0,0, 0 */ 

/* 10000, 0, 0 */ 


dp__getindexdef() gets the following default values for index properties: 


dp indexhdi sphdl; 
dp bool useclass; 
dp bool usealter; 
XString class; 
XString alter; 


/* IDX UNIT (index as a unit) */ 
/* FALSE */ 

/* FALSE */ 

/* NULL */ 

/* NULL */ 


dp _getpagedef() gets the following default values for page properties: 


dp pagedims dims; 
unsigned short tmgn; 
unsigned short bmgn; 
unsigned short Imgn; 
unsigned short rmgn; 

dp pageside stpagside; 
unsigned bindwidth; 
unsigned ncol; 

dp bool bicol; 

dp bool uneqcol: 
unsigned short colsp; 

dp colwidths *colwidths; 
dp coldirct coldirct; 

dp hdfttype hdfttype; 
dp bool hdthispage; 
dp bool hdsamepage; 
dp bool ftthispage; | 
dp bool ftsamepage; 
dp horpos hdpos; 

dp horpos ftpos; 

dp pntype pagnumtype; 
dp verpos vnum; 

dp _horpos hnum; 
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/* 842, 595 */ 

/* 72*/ 

/* 72 */ 

/* 72 */ 

/* 72 */ 

/* PS LEFT */ 
/*0*7- 

[*7*/ 

/* FALSE */ 

/* FALSE */ 

/*18*/ 

/* NULL */ 

/*CD_ LR (left to right) */ 
/* HFT CONT (continue) */ 
/* TRUE */ 

/* TRUE */ 

/* TRUE */ 

/* TRUE */ 

/* HP CENTERED */ 
/* HP CENTERED */ 
/* PNT NONE */ 

/* VP TOP */ 

/* HP RIGHT*/ 
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unsigned stpagnum; 


dp__getcolwidthdef() gets the following default value of column width property: 


unsigned short w; 


dp __getparadef() gets the following default values for paragraph properties: 


dp basprops basprops; 


dp tabstops tabstops; 
XString stylename; 
dp_paraelmarr ntrelm; 


dp __getbaspropsdef() gets the following default values for basic properties: 


unsigned short prelead; 
unsigned short poslead; 
unsigned short lindent; 
unsigned short rindent; 
unsigned short Inh; 

dp paralign paralign; 
dp bool just; 

dp bool hyph; 

dp bool kpnext; 

dp lang lang; 

dp strsuc strsuc; 

dp deftabsp deftabsp; 
dp__tabalign deftabal; 


/* 4 */ 


/*Q*/ 


/* 0, NULL */ 
/* NULL */ 


/* 0 */ 

/*0*/ 

/*0*/ 

/* 0 */ 

/*12*/ 

/* PA LEFT */ 

/* FALSE */ 

/* FALSE */ 

/* FALSE */ 

/* LANG USE(USEnglish) */ 
/*SS LR (left to right) */ 
/* 18 */ 

/* TSA_LEFT */ 


dp__gettabstopdef() gets the following default values for tab stop: 


dp bool dotid; 

dp bool eqsp; 
dp taboffset offset; 
dp_tabalign align; 


dp __getmodedef() gets the following default values for mode properties: 


dp bool strct; 

dp bool nonprint; 
dp bool cover; 
dp bool prompt; 


dp __getfontstyledef() gets the following default values for font style properties: 


dp fontprops props; 
XString desc; 
unsigned short softpos; 


unsigned short stylepos; 


dp _getparastyledef() gets the following default values for paragraph style properties: 


dp paraprops props; 
XString desc; 
unsigned short softpos; 


unsigned short stylepos; 


/* FALSE */ 

/* FALSE */ 
/*0*/ 

/* TSA _LEFT */ 


/* FALSE */ 
/* FALSE */ 
/* FALSE */ 
/* FALSE */ 


/* NULL */ 
/* 0 */ 
/* 0 */ 


/* NULL */ 
/* 0 */ 
/* 0 */ 
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dp__gettframedef() gets the following default values for text frame properties: 


XString name; /* NULL */ 

XString description; /* NULL */ 

unsigned innermargin; /* 141 */ 

dp orient orientation; /*OR_ HOR (horizontal) */ 
dp bool lastlinejust; /* FALSE */ 

dp bool autohyphen; /* FALSE */ 


dp __getfontelmarralltrue() initializes all font elements properties to TRUE. 
dp__getparaelmarralltrue() initializes all paragraph elements properties to TRUE. 
dp _getpagedel() gets the XCCS code of the page number delimiter. 
dp__gettoc() gets the XCCS code of the table of contents characters. 

RETURN VALUE 


If the call is successful 0 is returned, otherwise -1 is returned. The function getsigno() is used to get the 
reason for the failure. 


ERRORS 


dp _get*def() will fail if one or more of the following are true: 
Doc BadParm One of the arguments specified is invalid. 
Doc _ IllegalHandle The specified handle is illegal.. 


Doc TimeOut Inter-process communication has exceeded the maximum allowed time. 
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gi__intro 


NAME 


gi__intro - introductory explanation of graphics functions 
DESCRIPTION 


The functions in this section provide utilities for the creation and enumeration of anchored graphics, 
nested graphics, and CUSP button frames. The majority of these functions use Document IC Definitions 
and Document IC Property Definitions. Therefore, in addition to a familiarity with the Document Editor, 
you should also be familiar with these two sections of this manual before proceeding to use Graphics IC 
functions. 


Creating Graphics 


Graphics creation is initiated by a call to gi startgr(). This function creates a frame in a document and 
returns an object called a handle. The resulting frame is a container in which may be placed graphics data, 
thus it is called a graphics container. A graphics container is defined as an object that can contain graphic 
objects and may be one of three basic types: an anchored graphics frame, a nested graphics frame, or a 
CUSP button within a graphics frame. The type of container it becomes is dependent upon the gi_ start*() 
function that is called next, such as gi startnbtn() or gi startcluster(). Once a specific type of graphics 
container has been created, various gi ~ ad*() functions may be called to add graphic objects, such as curves, 
rectangles, bitmap graphics, and text frames 


The handle is an opaque type that identifies the graphics frame in which will be placed graphics data and 
is, therefore, passed as an argument to the gi_ad*() functions. 


A nested frame is a frame that is placed within a larger frame. Nested frames may be one of several types, 
such as non-anchored graphics frames, CUSP buttons, or graphics clusters. gi startgframe(), 
gi startnbtn(), or gi_startcluster() are called to create the corresponding nested frame. Each procedure 
takes a graphics container as an argument, and returns another graphics handle. The resulting handle is 
then passed as an argument to other gi _ad*() functions. 


When everything has been added to a graphics container, the final step is a call to the respective 
gi__finish*() routine. These routines are gi_finishgr(), gi finishnbtn(), gi finishgframe(), or 
gi_finishcluster(). gi__finishgr() returns a graphics instance which can then be passed to di_apafra me(). 


The typical scenario for creating a document with a floating graphics frame nested within an anchored 
graphics frame is as follows: 
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Call di_create() to obtain a document handle (doc). 

Call gi__startgr(doc) to get an anchored frame handle (h). 

Call gi__ad*(h) to add graphics to the anchored frame. 

Callgi__startgframe(h) to get a handle for a nested graphics frame (gfh). 

Call gi__ad(gfh) to add graphics to the nested frame. 

Call gi_finishgframe(gfh) to finish the nested frame. 

Call gi__finishgr(h) to complete the anchored frame and obtain an object of type di__ins. 


Call di__apaframe(h). 


© OD NDA PF wo W 


Call di_finish(&doc). 


Reading Graphics 


There are also GraphicsIC functions that read the contents and properties of a graphics frame. The 
gi enumerate() function is called to retrieve the contents or properties of a frame. It requires a graphics 
container and a set of user-defined call-back procedures as arguments. There is one call-back procedure 
for each type of object. Object types are defined as bar chart, bitmap frame, CUSP button, cluster, curve, 
ellipse, form field, graphics frame, line, line chart, pie chart, pie slice, point, rectangle, text, and triangle. 


gi enumerate() reads the contents of the graphics container, calling the appropriate procedure for each 
object type encountered. Ifa call-back procedure is not supplied for a particular type of object and that type 
of object is encountered during enumeration, that object will be ignored. Since call-back procedures are 
user-defined, they may be used to stop enumeration based upon a user-specified set of conditions. 


Similarly, gi enumbtnprog() accepts a set of user-defined call-back procedures to enumerate the contents 
of a CUSP button. 


Cross References 


3-2 


The following pages contain charts that should be used to facilitate the selection and application of gi *() 
functions. The charts are organized by category, or type of frame. When applicable, each category shows 
the types of objects that may be placed within the corresponding frame. The columns to the right of the 
categories list the functions that may be called to create an object or enumerate it. 


Page numbers for each function may be found in either the table of contents or index. 
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Category of Anchored Graphics and Anchored Button Frames 








Frame 








gi setgframeprops 






Anchored Button 
Frame 





di 
= 
gi_finishgr 
gi 
gi 
i 


aay Objects 
common fo 


Objects gi__adellipse 


Rectangle gi _adrectangle 
Triangle gi_adtriangle 


| Pie Slice . gi pisice 
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Category of Graphic Objects and Related Functions 
















Reading 
Function Name: 


gi enumerate 


gi pointproc 


gi_lineproc 


gi curveproc 


gi_ellipseproc 


gi _rectangleproc 


gi_triangleproc 


gi_pislceproc 
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Category of G 


Frame 
Form Field 


Nested 


Graphics Frame 


Nested Table 





Nested Button 
Frame 





Chart 


Others Cluster 


raphic Objects and Related Functions 





| 
i _adtframe 
gi _adffield | 
gi_startgframe gi _frameproc 

gi_finishgframe a | 
gi_startnbtn 


gi enumbtnprog 





gi_finishnbtn 


gi_relbtnprog 
gi _apchartobtnprog 
gi apnparatobtnprog 


gi_aptexttobtnprog 


gi_finishcht ae 


gi_clusterproc 


gi _startcluster 


gi_finishcluster 
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gi__adbacht 


NAME 
gi__adbacht - add bar chart 


SYNOPSIS 
#include “DoclC.h” 


#include “DociCProps.h” 
#include “GraphicsiC.h” 


int 
gi adbacht(h, box, props, data, wchild, ret) 
~ gi handleh; 
gi box *box; /* NULL */ 
gi bachtprops *props; /* NULL */ 
gi chtdat *data; 
dp bool wchild; /* FALSE */ 
gi_handle *ret; /* Returned */ 
DESCRIPTION 


The gi__adbacht() function is used to add a bar chart to a graphics container. This function draws a bar 
chart based on the properties specified by gi_bachtprops. 


The h argument is the graphics container handle returned by an earlier call to gi_startgr(), 
gi__startgframe(), gi__startbtn(),gi__startnbtn(), or gi__startcluster(). 


The box argument is a pointer of the type gi box. It’s two members, place and dims specify the origin of 
the bar chart and its size, relative to the graphics container. 


gi_place place; 
gi_dimsdims; 


gi_place contains two integer variables x and y. These two variables indicate the grid location of the box 
origin. gi_dims contains two integer variables w and h. These two variables indicate the width and height 
of the frame with respect to the box origin. Both place and dims are specified in units of micas. 


A {0, 0} grid location indicates the upper-left corner of the frame. Increasing the value of x causes the 
placement location to shift towards the right. Increasing the value of y causes the placement location to 
shift downwards. It is illegal to specify negative w and h values 


box.dims defines the size of the bar chart. Increasing the value of w causes the frame to grow towards the 
right. Increasing the value of h causes the frame to grow in a downward direction. 


The props argument is a pointer of the type gi bachtprops. It is a structure whose members specify the 
properties the resulting bar chart is to have. gi__bachtprops contains the following members: 


double units; 
unsigned div; 

gi barscale scale; 
dp color sclcol; 

gi _balayout layout; 
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gi baspacing spacing; 
gi _baorient orient; 
dp bool key; 

dp bool bafloat; 

dp bool mirror; 

gi chtapps *apps; 
dp bool joined; 


units, div, scale, sclcol, layout, spacing, orient, key, bafloat and mirror control some aspect of the bar 
chart’s appearance. These members accept the same values as their counterparts in the bar chart 
property sheet. 


units is a positive real number value that specifies the interval at which numeric indicators are placed 
on the scale. For example, a value of 2.5 means that all the numbers accompanying the scale will be 
divisible by 2.5. Therefore, only the numbers 2.5, 5.0, 7.5, etc. will be displayed. 


div is a whole number between 0 and 65,535 that specifies the number of hash marks, or divisions, 
that are to occur between each numeric indicator on the scale. 


scale is of the type gi__barscale. It is an enumerated variable that specifies the gauge to be used when 
displaying the bar chart. It may have one of the following values: 


BS STICK /* single tick */ 
BS DTICK /* double tick */ 
BS DGRID /* double grid */ 
BS _OGRID /* open grid */ 


sclcol is a structure of the type dp__color. It specifies the color to be used in drawing the bar chart scale. 


layout is of the type gi balayout. It is an enumerated variable that defines how the components 
comprising each bar in the chart is to be placed with respect to the other components. layout may have 
one of the following values: 


BL STACKED /* place each component on top of the other component(s) */ 
BL GROUPED /* place components next to each other */ 


spacing is of the type gi_baspacing It is an enumerated variable that defines the separation between 
bar chart elements. It may have one of the following values: 


BSP MERGED /* merged */ 

BSP JOINED /* joined */ 

BSP QUARTER /* quarter spacing */ 

BSP HALF /* half spacing */ 

BSP THREEQUART /* three-quarter spacing */ 
BSP BRIDGED /* bridged */ 


orient is of the type gi baorient. It is an enumerated variable that defines the direction in which the 
bar chart data is to be drawn. The data may be drawn from the bottom of the frame to the top, or from 
the left edge of the frame to the right. orient may have one of the following values: 


BO VER | /* vertical */ 
BO HOR /* horizontal */ 


key is a Boolean value that, when set to TRUE, displays the explanatory notes in the bar chart. 


bafloat is currently not supported. 
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mirror is currently not supported. 


apps is a pointer of the type gi chtapps. It is a structure that specifies the visual properties of the bars 
in the bar chart. It is used to define the color of the lines, the fill patterns, the color of the filled bars, 
etc. It contains the following members: 


unsigned length; 
gi_chtapp *values; 


where, gi__chtapp contains the following members: 


gi gray gray; 

gi textures txrs; 
dp color txrcol; 
dp color shdcol; 
dp__color Incol; 


gray isofthetypegi gray an enumerate type that specifies the amount of black, or saturation, 
to make varying shades of the color gray. It may have one of the following values: 


GRY NONE 
GRY GRAY25 
GRY GRAY50 
GRY GRAY75 
GRY BLACK 


The number following the respective GRY _GRAY* indicates the percentage of saturation. 
For example, 


GRY NONE 
GRY__GRAY25 


GRY_GRAY50 [s 
GRY__GRAY75 
GRY BLACK 





txrs is of the type gi textures. It is a structure that defines the direction in which the fill 
patterns are drawn in the resulting bars. It may have one of the following values: 


dp bool vertical 
dp bool horizontal 
dp bool nwse 

dp boolswne 

dp _bool polkadot 


txrcol, shdcol, and Incol are the respective colors of the fill pattern, the shading, and the lines 
used to draw each bar in the bar chart. shdcol is only available when gray is set to 
GRY BLACK. 


joined is a Boolean value that specifies whether the elements of the bar chart are to be merged as one 
with the bar chart, or if they are to remain separate graphic elements. If joined is FALSE, each 
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graphics element, such as rectangles and lines, will be independent of the bar chart and may be 
manipulated accordingly. 


data is a pointer of the type gi__chtdat. It is a structure whose members define the common data of the 
chart. It contains the following members: 


XString title; 

gi dataset datset; 
dp lang lang; 

gi datsource datsou; 
gi labels *collabl; 

gi labels *rowlabl; 
gi_datvalues *values; 


title is of the type XString and is used to specify the name of the bar chart. 


dataset is of the type gi dataset. It is a structure that specifies the axis at which bar titles are to be 
drawn. It may have one of the following values: 


DAS COLUMN /* column */ 
DAS ROW /* row */ 


lang is of the type dp lang, an enumerated variable that defines the language to be used in writing 
bar chart text. It may have one of fifteen values, suchas LANG USEorLANG JPN. Refer to the section 
in Document IC Property Definitions, titled Basic Property Records. under the heading of lang for a 
description of acceptable values. 


datsou is of the type gi_datsource, a structure that specifies the source that is to supply the data used 
to draw the individual bars of the bar chart. It contains the following members: 


enum { 
DTS PS, /* datain chart property */ 
DTS DOC /* data in document */ 

} type; 

union { 
gi tbifillin fillin; /* effective when type is DTS PS */ 
gi tbicont doc; /* effective when type isDTS DOC */ 
}u; 

fillin is of the type gi__ tblfillin and may have one of the following values: 
TFO BYROW /* by row */ 
TFO BYCOL /* by column */ 


gi__tblcont contains the following members: 


XString name; 
gi_sousubset subset; 


gi_sousubset contains the following members: 


gi elmrange colrange; 
gi elmrangerowrange; 
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gi_elmrange contains the following members: 


unsigned first; 
unsigned last; 


The Document Editor may use two types of data from two different sources. One type and source of 
data is that from the chart property. The other is data from within a document. DTS PS specifies 
that the source data for drawing bar charts is in the chart. DTS DOC specifies that that the source 
data for drawing the bars is in a table frame in the same document. If DTS DOCis specified, name 
must also be specified. When data is supplied from a chart property, gi_datsou rce should be set as 
follows: 


gi datsource datasource; 


datasource.type = DTS__ PS; 
datasource.u-fillin = TFO_BYROW (or TFO_BYCOL); 


When table data in a document is used as the source, gi datsource should be set as follows: 
gi_datsource datasource; 


datasource.type = DTS DOC; 
datasource.u.doc.name = (XString)tablename; 
datasource.u.doc.subset.colrange.first = 0; 
datasource.u.doc.subset.colrange.last = 0; 
datasource.u.doc.subset.rowrange.first = 0; 
datasource.u.doc.subset.rowrange.last = 0; 


collabl and rowlabl are both pointers to gi labels, a structure that specifies respective column and row 
bar titles. gi_labels contains the following members: 


unsigned length; 
XString (*values); _ /* array of XString */ 


values is a pointer of the type gi datvalues, a structure that specifies the values of text strings and 
numbers in the bar chart. It contains the following members: 


enum { 
RS STRING, 
RS NUMERIC 
} format; 
union { 
gi strowcont string; /* effective when formatisRS STRING */ 
gi__numrowcont numeric; /* effective when format is RS__ NUMERIC */ 
}u; 7 


gi__strowcont contains the following members: 


unsigned length; 
gi_strow *strow; /* array of gi__strow */ 


gi_numrowcont contains the following members: 


unsigned length; 
gi numrow *numrow; = /*arrayofgi numrow*%*/ 
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strow is a pointer of the type gi strow, a structure that contains an array of XString and its 
length.It represents the string data that is to be filled in the row. It contains the following 
members: 


unsigned length; 
XString *values; /* array of XString */ 


numrow is a pointer of the type gi_numrow. It is a structure that contains an array of double 
and its length. It represents the numeric data to be filled in the row. It contains the following 
members: 


unsigned length; 
double *values; /* array of double */ 


The data types RS__STRINGor RS_ NUMERIC are used as switches to select the elements of types, string 
or numeric. _ 


wchild is a Boolean that, when set to TRUE, will cause a handle to the graphics elements in the bar chart to 
be returned in ret. After which, graphic elements may be added to the handle. When set to FALSE, ret will 
contain a NULL value and the Document Editor will rebuild the bar chart from the information contained in 
gi_chtdat. If a handle is returned, gi__finishcht() must be called to release it when done. 


RETURN VALUE 


If the call is successful 0 is returned, otherwise -1 is returned. The function getsigno() is used to get the 
reason for the failure. 


ERRORS 


gi_ad bacht() will fail if one or more of the following are true: 


Doc DocumentFull No more room inthe document. 


Doc _ReadonlyDoc Document opened in ReadOnly mode. 


Doc OutOfDiskSpace Not enough disk space for the operation. 


Doc OutOfVM Not enough virtual memory for the operation. 


Doc _BadParm One of the arguments specified is invalid. 


Doc_IllegalHandle The specified handle is illegal. 


Doc TimeOut Inter-process communication has exceeded the maximum allowed time. 


SEE ALSO 


gi_finishcht() 
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gi__adbm 
NAME 

gi__adbm - add bitmap 
SYNOPSIS 


#include “DociC.h” 
#include “DociCProps.h” 
#include “GraphicsiC.h” 


int 
gi adbm(h, box, bmprops, frprops, wtcap, wbcap, wicap, wrcap, ret) 
~ gi handleh; 
gi box *box; /* NULL */ 
gi bmprops *bmprops; /* NULL */ 
gi frameprops *frprops; /* NULL */ 
dp bool wtcap; /* FALSE */ 
dp bool wbcap; /* FALSE */ 
dp bool wicap; /* FALSE */ 
dp bool wrcap; /* FALSE */ 
ret_adbm *ret; /* Returned */ 
DESCRIPTION 


The gi__adbm() function is used to add a bitmap graphic to the graphics container. 


The h argument is the graphics container handle returned by an earlier call to gi_startgr(), 
gi_startgframe(), gi__startbtn(), gi__startnbtn(), or gi__startcluster‘(). 


The box argument is a pointer of the type gi box. Its two members, place and dims. specify the origin of 
the area in which the bit map will be placed and its size, relative to the graphics container (including 
caption area). Refer to gi _adffield() for a description of gi_box. 


The bmprops argument is a pointer of the type gi bmprops. It is a structure whose members control 
visual aspects of the bit map graphic. It contains the following members: 


int xoffset; 

int yoffset; 

XString prntfile; 

gi bmdisp dispsou; 

gi bmscalprops scalprops; 
dp bool remotefile; 

dp _color bitcol; 


xoffset and yoffset have no affect on the outcome ofa call togi__adbm(). 
prntfile is the full path name, or source, of the bitmap object to be printed. It is the means by which a 
different bitmap file may be accessed during the printing of the finished document than that being 


accessed when displaying the document. The value of this parameter is usually the same as the 
display source. 
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The source 
internal to 


for the bitmap object to be placed in a document may be in one of two locations: either 
the file (e.g., the bits are copied into the document), or in a file on the desktop (e.g., a 


pointer to the bits is inserted into the document). dispsou is of the type gi__bmdisp. It is a structure 
that specifies the display source of the bitmap object and whether the bitmap object is to be inserted or 
pointed to. gi_bmdispcontains the following members: 


enum { 
BM 


INTERNAL, 


BM_ FILE 
} type; 


union { 


gi_bmdat *bm; /* effective when type is BM_INTERNAL */ 
XString name; /* effective when type isBM_ FILE */ 


yu; 


The physical aspects of the actual bitmap object is described by the structure gi_bmdat.gi__bmdat 
contains the following members: 


gi rational xscl; 

gi rational yscl; 

unsigned xdims; /* # of bits wide */ 

unsigned ydims; /* # of bits tall */ | 

unsigned bpl; /* Bits Per Line = ((xdim + 15)/16) * 16 */ 
char *bitdata; 


xscl and yscl are of the type gi rational. It is a structure that specifies the scale at which to 
display the bitmap object in both x and y axis direction. gi__rational contains the following 
members: 


intnum; 
unsigned den; 


num and den are abbreviations of numerator and denominator, respectively. These two 
values are used to perform unit conversions from points to meters by specifying the 
resolution of the bitmap data. The base conversion involves converting dots per inch (dpi) 
into units of meters. For example, the desktop has a resolution of 72 dpi, therefore, for 
bitmap data created on the desktop, as one inch is equal to 0.0254 meters and there are 
720,000 points in 254 meters, xscl and yscl should be set to {254, 720000}. If the bitmap 
data is created by a scanner, the resolution should be set to correspond to the resolution of 
the scanner. For example, if the scanner has a resolution of 200 dpi, then set xscl and yscl 
to {250, 200000}. If the resolution of the scanner is 300 dpi, then the correct values would 
be {254, 300000}. | 


xdims and ydims are unsigned integers that specify the x and y axis dimensions of the bitmap 
object in units of bits. 


bpl is the real bitmap data per line. bp] must have a word boundary. For example: 
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24 bits 


10101010 10101010 1010101000000000 AAOOH, 

0101010 1010101010101010 100000000 5500H, 
10101010101010101010101000000000 AAOOH, 
01010101010101010101010100000000 5500H, 
10101010101010101010101000000000 AAOOH, 
010101010101010101010 10100000000 5500H, 
10101010101010101010101000000000 AAQOH, 

0101010 1010101010101010 100000000 5500H, 
1010101010101010101010 1000000000 AAQOH, 

Dot of of of ot ff 01010101010101010101010 100000000 5500H, 
i a PJ iio ot ft ft 2 1010101010101010101010 1000000000 AAOOH, 


Fs 
BHEeEBEBHeHEeHEeEHEEEE Doro ot ot of ff ft 01010101010101010101010100000000 5500H, 
i oe oe oe oe oo hl hoe hl OCU SCO ll tt tt ttf) 10101010101010101010101000000000 AAOOH, 
i i oe oe oe oe oe oe he he he SF tt ff 10101010101010101010101000000000 5500H, 


01010101010101010101010100000000 AAQOH, 


1010101010 1010 101010101000000000 5500H, 


Ban]: ot: 2: tt 01010101010101010101010100000000 AAQOH, 
BEBEeEeEEHEH foi ft fot ft ff 10101010101010101010101000000000 5500H, 


01010101010101010101010100000000 AAOQOQOH, 
1010 101010101010101010 1000000000 5500H, 
01010101010101010101010100000000 AAOQOH, 
01010101010101010101010 100000000 5500H, 
10101010101010101010101000000000 AAOOH, 
01010101010101010101010100000000 5500H, 


32 bits 





xdims = 24 
ydims = 24 
bpl =: 32 
bitdata — ae 


AAAAH, AAOOH, 5555H, 5500H, 
AAAAH, AAOOH, 5555H, 5500H, 
AAAAH, AAQOH, 5555H, 5500H, 
AAAAH, AAOQOH, 5555H, 5500H, 
AAAAH, AAOOH, 5555H, 5500H, 
AAAAH, AAOOH, 5555H, 5500H, 
AAAAH, AAOOH, 5555H, 5500H, 
AAAAH, AAOOH, 5555H, 5500H, 
AAAAH, AAOOH, 5555H, 5500H, 
AAAAH, AAOOH, 5555H, 5500H, 
AAAAH, AAOOH, 5555H, 5500H, 
AAAAH, AAOQOH, 5555H, 5500H, ..... 


bitdata is a pointer to to the bitmap data. The size of the bitmap data is to be equal to ( xdims 
* bpl). 
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scalprops is a structure of the type gi_bmscalprops. It is used to specify the manner in which the 
bitmap is displayed. gi__bmscalprops contains the following members: 


enum { 
BMS PRNTRES, 
BMS FIXED, 
BMS AUTOMATIC 
} type; 
union { 
unsigned res; /* effective when type is BMS PRNTRES*/ 
gi scalfix fixed; /* effective when type is BMS FIXED */ 
enum { /* effective when type is BMS AUTOMATIC */ 
SHP_ SIMILAR, _ 
SHP FILLUP 
} shape; 
}u; 


gi_scalfix contains the following members: 


enum { 
HAL CENTER, 
HAL RIGHT, 
HAL LEFT 
} halign; 

enum { 
VAL CENTER, 
VAL BOTTOM, 
VAL TOP 
} valign; 


unsigned percent; 


scalprops permits the user to specify one of three bitmap scaling modes: BMS_PRNTRES, BMS _FIXEDor 
BMS AUTOMATIC. 


BMS __PRNTRES causes the bitmap object to be printed at the resolution specified in the res 
argument. 


BMS _ FIXED requires the user to control the bitmap’s alignment (via halign and valign parameters) 
and scaling (via xscl and yscl). The printing of the bitmap object is also affected by the value of the 
percent argument. (See percent below.) 


BMS AUTOMATIC, with shape = SHP SIMILAR, results in the bitmap object being enlarged or 
reduced to fit just inside the bitmap frame until either the vertical or horizontal edge of the bitmap 
object touches the graphic frame’s edge. The aspect ratio of the bitmap object is maintained. This is 
usually the default mode. BMS AUTOMATIC, with shape = SHP FILLUP, results in the bitmap 
object being scaled to fit the entire graphic frame. The aspect ratio is not maintained. 


If BMS __PRNTRESor BMS __ FIXED is selected, SHP__ SIMILAR and SHP_FILLUP will be ignored. 


The percent parameter allows the user to shrink or magnify the bitmap object, while maintaining its 
aspect ratio. A percent value of 100 means that the bitmap should be displayed and printed the same 
size as the original. A value of 50 means that the bitmap is shrunk to one-half both vertically and 
horizontally. percent must be an integer ranging from 1 to 1000, inclusive. This parameter is only 
available when the value of type is set to BMS__PRINTRES. 


The value of res specifies the resolution to be used in printing the bitmap object. It is usually set to the 
same resolution as the printer on which the bitmap object is to be printed. Standard values are 72, 75, 
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150, 200, and 300. Other values may be specified. Values are specified in units of dots-per-inch (dpi). 
This parameter is only available when the value of type is set to BMS__ PRINTRES. 


The remotefile parameter is used to specify whether the prntfile is in a file or on the desktop. 


The bitcol parameter is a structure of the type dp color. Its members describe the color of the dots. 
Refer todp__col* for more information. 


The frprops argument is a pointer of the type gi frameprops. It is a structure that defines the common 
properties of the graphics frame. Refer to the description of frprops in gi_startgframe() for more 
information. 


w*cap arguments are Boolean values that specify whether or not the frame is to have captions. If a value 
of TRUE is specified for a w*cap argument. the respective *cap return value will be non-NULL. These 
caption arguments are used to set the top, bottom, left, and right captions, respectively. Related DociC 
functions may then be used to add text to each caption. Note that each caption must eventually be freed by 
acalltodi__relcap(). 


RETURN VALUE 


If the call is successful 0 is returned, otherwise -1 is returned. The function getsigno() is used to get the 
reason for the failure. 


ERRORS 


gi__adbm() will fail if one or more of the following are true: 
Doc DocumentFull No more room in the document. 
Doc ReadonlyDoc Document opened in ReadOnly mode. 


Doc OutOfDiskSpace Not enough disk space for the operation. 


Doc OutOfVM Not enough virtual memory for the operation. 

Doc BadParm One of the arguments specified is invalid. 

Doc_IllegalHandle The specified handle is illegal. 

Doc_ TimeOut Inter-process communication has exceeded the maximum allowed time. 
SEE ALSO 


dp__namefromcol(),dp__wkcolfromcol(), gi__startgframe() 
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gi__adcurve 


NAME 


gi__adcurve - add curve 
SYNOPSIS 


#include “GraphicsiC.h” 


int 
gi__adcurve(h, box, props) 
gi_handleh; 
gi_box *box; /* NULL */ 
gi_curveprops *props; /* NULL */ 
DESCRIPTION 


The gi adcurve() function is used to add a curve of a specific size and shape to a graphics frame. 


The h argument is the graphics frame handle returned by anearliercalltogi_startgframe(),gi__startbtn(), 
gi_startnbtn. gi__startgr(),orgi__startcluster(). 


The box argument is a pointer of the type gi__box. It’s two members, place and dims specify the origin 
of the object and its size, relative to the frame. 


gi_place place; 
gi_dims dims; 


gi__place contains two integer variables x and y. These two variables indicate the grid location of the box 
origin. gi_dims contains two integer variables w and h. These two variables indicate the width and height 
of the box with respect to the box origin. Both place and dims are specified in units of micas. 


A {0, 0} grid location indicates the upper left corner of a frame. Increasing the value of x causes the 
placement location to shift towards the right. Increasing the value of y causes the placement location to 
shift downwards. It is illegal to specify negative w and h values, therefore an object’s dims.place must 
always correspond to the upper left corner of a box. It is legal to specify negative x and y values. 


box.dims defines the area in which may be placed graphic objects. Increasing the value of w causes the 


frame to grow towards the right. Increasing the value of h causes the frame to grow in a downward 
direction. 
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The props argument is a pointer of the type gi__curveprops. It is a structure that defines the the 
appearance and shape of the curve. gi__curveprops contains the following members: 


gi brush brsh; 

gi Inend Inenw; 
gi Inend Inese; 

gi Inedhd Inhnw; 
gi Inedhd Inhse; 
gi place pinw; 
gi__ place plapx; 

gi place plse; 

gi_ place plpek; 
dp bool eccentric; 
unsigned eccentricity; 
dp__bool fixangle; 


brsh is of the type gi_ brush. It specifies the type of line used to draw the brush, such as solid or dashed, 
and the brush color. Refer to the description of gi startgframe() for general information regarding 
brsh. The exception to the description of brsh in gi startgframe() is with regards to the stylebrush 
member. The two parameters that may not be specified are STB_ INVISIBLE and STB DOUBLE. The 
remaining parameters will result in curves having the appearances as shown below: 


Not c 
Allowed ( Allowed ‘ 


INVISIBLE SOLID DASHED DOTTED DOUBLE BROKEN 
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Inenw and Inese are enumerated variables that describe the appearance of the end points of the curve. 
Each end point may have one of the following values: 


LE FLUSH /* flush */ 

LE SQUARE /* square */ 

LE ROUND /* round */ 

LE ARROW /* arrowhead*/ 


Inenw defines the end that is painted first and Inese defines the end that is painted last. The curve is 
always traced in a clockwise direction, as shown in the figure below). . 





Defining Line Curves 


If either Inenw or Inese is assigned a value of LE ARROW, then the value of Inhnw and/or Inhse 
specifies the type of arrowhead to be placed at the endpoint(s) of the curve. Note that Inhnw specifies 
the type of arrowhead for Inenw and Inhse specifies the type of arrowhead for Inese. 


Inhnw and/or Inhse may have one of the following values: 


LEH NONE /* none */ 
LEH H1 /*h1 */ 
LEH H2 /*h2*/ 
LEH H3 /* h3 */ 


LEH H1is the finest point;LEH _H3 is the most blunt, as shown in the figure below. If Inenw and/or 
Inese is not assigned a value of LE ARROW, then Inhnw and/or Inhse should be left LEH NONE. 


The pl* parameters define the curve by specifying its end points, apex, and peak. These points are 
relative to the frame defined by the box argument, not the frame itself. Curves are traced in a 
clockwise direction, therefore, be sure that the NW endpoint appears before the SE endpoint when 
tracing a curve. The figure below illustrates the four pl* points used to define two different curves; the 
triangle marks the apex, the square marks the peak, and the circles mark the endpoints. 


Another way to define a curve is by specifying the curve’s endpoints, apex and eccentricity. 
eccentricity is a fraction used to specify the swell of a curve, as shown below. 
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——— > h2 
_——_ +3 
Types of Arrowheads 





Defining Curves 


The fraction is derived by the following equation: 





Defining Eccentricity 


eccentricity = b/(a + b) * 65535 


The eccentricity argument is a Boolean value that, when set to TRUE, indicates that eccentricity is to 
be used rather than pl* points. 


The fixangle parameter is a Boolean value that, when set to TRUE, indicates that the curve is to 
maintain its shape when grown or shrunk. 


RETURN VALUE 


If the call is successful 0 is returned, otherwise -1 is returned. The function getsigno() is used to get the 
reason for the failure. 
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ERRORS 


gi_adcu rve() will fail if one or more of the following are true: 
Doc DocumentFull No more room in the document. 
Doc ReadonlyDoc Document opened in ReadOnly mode. 


Doc OutOfDiskSpace Not enough disk space for the operation. 


Doc OutOfVM Not enough virtual memory for the operation. 

Doc _BadParm One of the arguments specified is invalid. 

Doc_illegalHandle The specified handle is illegal. 

Doc TimeOut Inter-process communication has exceeded the maximum allowed time. 
SEE ALSO 


gi _startgframe() 
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NAME 
gi__adellipse - add ellipse 


SYNOPSIS 


#include “GraphicsIC.h” 


int 
gi_adellipse(h, box, props) 
gi_handleh; 
gi box *box; /* NULL */ 
gi_ellipseprops *props; /* NULL */ 
DESCRIPTION 


The gi _adellipse() function is used to add an ellipse to a graphics container. 
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The h argument is the graphics container handle returned by an earlier call to gi_startgframe(), 


gi_startgr(), gi_startbtn(), gi_startnbtn(), or gi _startcluster(). 


The box argument is a pointer of the type gi box. It’s two members, place and dims. specify the origin of 
the box in which the ellipse will be placed and the area of the ellipse, relative to the graphics frame. Refer 


to gi__adcurve() for a description of gi__box. 


The ellipse will be placed in the resulting box such that the extreme edges of the ellipse touch the 
respective edge of the box, therefore, the size of the box determines the size of the ellipse. For example, 





The props argument is a pointer of the type gi_ellipseprops. It is a structure whose members define the 


appearance of the ellipse. Its members are: 
gi__brush brsh; 


gi_shading shade; 
dp_boolfixshape; 
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brsh is a structure that defines the visual qualities of the lines used in tracing the border of the ellipse. 
It contains the following members: 


unsigned wth; 


gi_stlbrush stylebrush; 
dp__color brushcolor; 


wth is the width of lines, specified in units of micas. The standard brush widths may have one of 


the following value: 


GSLW1 
GSLW2 
GSLW3 
GSLW4 
GSLW5 
GSLW6 


/* 1 width for Graphics Single Line */ 
/* 2 width for Graphics Single Line */ 
/* 3 width for Graphics Single Line */ 
/* 4width for Graphics Single Line */ 
/* 5 width for Graphics Single Line */ 
/* 6 width for Graphics Single Line */ 


Each value corresponds to 35, 71, 106, 141, 176, and 212 micas, respectively. Non-standard 
brush widths will result in an error. 


stylebrush defines how the lines are to be drawn, such as solid or dashed. It may have one of the 


following values: 


STB INVISIBLE 
STB SOLID 
STB DASHED 
STB DOTTED 
STB DOUBLE 
STB BROKEN 


/* invisible */ 
/* solid */ 

/* dashed */ 
/* dotted */ 
/* double */ 
/* broken */ 


The wth of STB DOUBLE borders is 3 times the usual width because it consists of two lines 
separated by a gap equal to the width of the line. In this case, the brush widths may have one of the 


following values: 


GDL W1 
GDL W2 
GDL W3 
GDLW4 
GDLW5 
GDL W6 


/* 1 width for Graphics Double Line */ 
/* 2width for Graphics Double Line */ 
/* 3 width for Graphics Double Line */ 
/* 4 width for Graphics Double Line */ 
/* 5 width for Graphics Double Line */ 
/* 6 width for Graphics Double Line */ 


Each value corresponds to 106, 212, 318, 423, 529, and 635 micas, respectively. The following 
are examples of brush styles: 


INVISIBLE 
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L._. 


SOLID DASHED DOTTED DOUBLE BROKEN 
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brushcolor specifies the color to be used to display the lines that make up the edges of the graphic 
object. The value of color may be any color that isa member of dp__color. 


shade is a structure of type gi__shading. It is used to define the appearance of the ellipse’s interior. Its 
members are: 


gi__gray gray; 

gi textures txrs; 
dp color txrcol; 
dp color shdcol; 


gray is of the type gi_ gray, an enumerated variable that specifies the percentage of black, or 
saturation, to be used in making varying shades of the color gray. Refer to gi_adbacht() for a chart 
illustrating the available shades. 


txrs is a structure of type gi textures. It specifies the direction in which the texture is drawn in the 
ellipse or the type of texture that is to be placed in the ellipse. For example, textures may be placed in 
an ellipse with a horizontal, vertical, or diagonal orientation. Also, a type of texture that may be 
placed in the ellipse is a polka dot pattern. gi_textures has the following members: 


dp bool vertical; 
dp bool horizontal; 
dp bool nwse; 

dp bool swne; 
dp__bool polkadot; 


Each variable is a Boolean value. The resulting texture will be the AND of the variables . That is, 
each variable that is set to TRUE will be placed as a texture in the graphic object. 


txrcol is a structure of type dp color. Its members define the color that is to be used in drawing the 
texture, or foreground, of the ellipse’s interior. 


shdcol is a structure of type dp__color. Its members define the color to be used when drawing the 
background in the ellipse’s interior. This parameter is enabled only when the value of gray is 
GRY BLACK. If the value of gray is any other value, shdcol is set toGRY__ BLACK. 
fixshape is a Boolean value that, when set to TRUE, indicates that the aspect ratio of a graphic object will 
remain intact when the user grows or shrinks the ellipse. A value of FALSE indicates that the aspect ratio 
of the ellipse will change freely. 
RETURN VALUE 


If the call is successful 0 is returned, otherwise -1 is returned. The function getsigno() is used to get the 
reason for the failure. 
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ERRORS 
gi__adellipse() will fail if one or more of the following are true: 

Doc DocumentFull No more room in the document. 
Doc ReadonlyDoc Document opened in ReadOnly mode. 
Doc OutOfDiskSpace Not enough disk space for the operation. 
Doc OutOfVM Not enough virtual memory for the operation. 
Doc BadParm One of the arguments specified is invalid. 
Doc_illegalHandle The specified handle is illegal. 


Doc TimeOut Inter-process communication has exceeded the maximum allowed time. 
SEE ALSO 


gi_ad bacht() 
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gi__adffield 
NAME 

gi__adffield - add form field 
SYNOPSIS 


#include “DociC.h” 
#include “DociCProps.h” 
#include “GraphicsIC.h” 


int 

gi _adffield(h, box, fiprops, frprops, tfprops, paprops, foprops, wfield, wtcap, wbcap, wicap, wrcap, ret) 
gi handle h; 
gi box *box; /* NULL */ 
dp fldprops *fldprops; /* NULL */ 
gi frameprops *frprops; /* NULL */ 
gi tframeprops *tfprops; /* NULL */ 
dp paraprops *paprops; /* NULL */ 
dp fontprops *foprops; /* NULL */ 
dp bool wfield; /* FALSE */ 
dp bool wtcap; /* FALSE */ 
dp bool wbcap; /* FALSE */ 
dp bool wicap; /* FALSE */ 
dp bool wrcap; /* FALSE */ 
ret__adffield *ret; /* Returned */ 

DESCRIPTION 


The gi__adffield() function is used to add a form field to a graphics frame. 


The h argument is the graphics container handle returned by an earlier call to gi_startgframe(), 
gi_startgr(),gi__startbtn(),gi_startnbtn(), or gi__startcluster(). 


The box argument is a pointer of the type gi__box. It’s two members, place and dims. specify the origin of 
the frame and its size, relative to the graphics container. 


gi_place place; 
gi_dims dims; 


gi place contains two integer variables x and y. These two variables indicate the grid location of the 
box origin (including the caption). gi dims contains two integer variables w and h. These two 
variables indicate the width and height of the frame with respect to the box origin. Both place and 
dims are specified in units of micas. 


A {0, 0} grid location indicates the upper-left corner of the graphics container. Increasing the value of x 
causes the placement location to shift towards the right. Increasing the value of y causes the 


placement location to shift downwards. It is illegal to specify negative w and h values 


box.dims defines the size of the frame. Increasing the value of w causes the frame to grow towards the 
right. Increasing the value of h causes the frame to grow in a downward direction. 


Refer to gi__startgframe() for a description of the box, *frprops, and w*cap arguments. 
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The fldprops argument is a pointer of the type dp _ flidprops. It is a structure whose members define the 
properties to be attributed to the resulting field. The members specify font properties, language, format, 
and soon. dp _fldprops has the following members: 


dp lang lang; 
unsigned length; 

dp bool req; 

dp skpchoice skpif; 
dp bool stpskp; 

dp fldchoice type; 
XString fill-in; 
XString desc; 
XString format; 
XString name; 
XString range; 
XString skpiffld; 
dp__fontruns *fillinruns; 


Refer to Field Properties in the section dp __intro for a description of each parameter. 


The tfprops argument is a pointer of the type gi_tframeprops. It is a structure whose members describe 
the properties of the text field and contains the following members: 


dp_bool expr; 
dp__bool expb; 
dp__tframeprops props; 


expr and expb are abbreviations for expand right and expand bottom, respectively. They are Boolean 
values. When both expr and expb are TRUE, the width and height can be changed according to the size of 
the text included. 


The props argument is a pointer of the type dp tframeprops. It is a structure whose members define the 
inner margin and orientation of the text within the frame, as well as the type of line justification and auto- 
hyphenation options. It contains the following members: 


XString name; 

XString description; 
unsigned innerMargin; 
dp orient orientation; 
dp bool lastLineJustify; 
dp bool autoHyphenate; 


Refer to Text Properties indp intro for a more thorough description. 


The paprops and foprops arguments are pointerstodp paraprops and dp__fontprops, respectively. They 
define the paragraph and font properties to be attributed to the resulting text field. See Paragraph 
Properties and Font Properties in the section dp __intro for a more complete description. 


The wfield argument is a Boolean value that, when set to TRUE, causes di adfield to return a handle toa 
field. The handle may then be passed as an argument to other text field manipulation functions. The 
w*cap arguments are Boolean values that specify if captions are desired along the top, bottom, left, or 
right edges of the text field. 
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This function sets the return information into the structure ret__adffield, which contains the following 
members: 


di_ field field; 

di caption tcap; 
di caption bcap; 
di caption Icap; 
di__caption rcap; 


When wfield is set to TRUE, gi adffield() will return di__field, a handle that may be used by other text field 
manipulation functions. This field handle must eventually be freed by a call to di__relfield(). Information 
may be added to this field by making calls to the respective gi_ad*() functions. 


RETURN VALUE 


If the call is successful 0 is returned, otherwise -1 is returned. The function getsigno() is used to get the 
reason for the failure. 


ERRORS 


gi_adffield() will fail if one or more of the following are true: 
Doc DocumentFull No more room in the document. 
Doc _ReadonlyDoc Document opened in ReadOnly mode. 


Doc OutOfDiskSpace Not enough disk space for the operation. 


Doc OutOfVM Not enough virtual memory for the operation. 
Doc BadParm One of the arguments specified is invalid. 
Doc_IllegalHandle The specified handle is illegal. 
Doc_TimeO ut Inter-process communication has exceeded the maximum allowed time. 
SEE ALSO 
di__relfield() 
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gi__adline 
NAME 

gi__adline - add line 
SYNOPSIS 


#include “GraphicsiC.h” 


int 
gi _adline(h, box, props) 
gi_handleh; 
gi_box *box; /* NULL */ 
gi_lineprops *props; /* NULL */ 
DESCRIPTION 


The gi_adline() function is used to add a line to a graphics container. 


The h argument is the graphics container handle returned by an earlier call to gi startgframe(), 
gi_startgr(), gi__startbtn(), gi startnbtn(), gi__startcluster(), gi_adpicht(), gi_adIncht(), or gi adbacht(). 


The box argument is a pointer of the type gi__box. Refer togi__adcurve() for a description of gi__ box. 


The props argument is a pointer of the type gi__lineprops. It is a structure whose members define the 
appearance and direction of the line. It contains the following members: 


gi brush brsh; 

gi Inend Inenw; 
gi__Inend Inese; 
gi Inedhd Inhnw; 
gi Inedhd Inhse; 
gi Indirct dirct; 
dp _bool fixangle; 


Refer to gi__adcurve() for a description of the members of gi_lineprops. 
RETURN VALUE 


If the call is successful 0 is returned, otherwise -1 is returned. The function getsigno() is used to get the 
reason for the failure. 
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ERRORS 

gi_adline() will fail if one or more of the following are true: 
Doc DocumentFull No more room in the document. 
Doc ReadonlyDoc Document opened in ReadOnly mode. 
Doc OutOfDiskSpace Not enough disk space for the operation. 
Doc OutOfVM Not enough virtual memory for the operation. 
Doc BadParm One of the arguments specified is invalid. 
Doc_IllegalHandile = The specified handle is illegal. 


Doc TimeOut Inter-process communication has exceeded the maximum allowed time. 
SEE ALSO 


gi_adcurve(),gi__adellipse() 
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gi__adIncht 


NAME 


gi__adI|ncht - add line chart 


SYNOPSIS 


#include “DociCProps.h” 
#include "GraphicsIC.h” 


int 
gi adincht(h, box, props, data, wchild, ret) 
~ gi handleh; 
gi box *box; /* NULL */ 
gi Inchtprops *props; /* NULL */ 
gi chtdat *data; 
dp bool wchild; /* FALSE */ 
gi_handle *ret; /* Returned */ 
DESCRIPTION 


The gi__adincht() function is used to add a line chart to a specified graphics container. 


Refer to gi_adbacht() for a description of the hand box arguments. 


The props argument is a pointer of the type gi__Inchtprops. It is a structure whose members specify the 
properties of the resulting line chart. gi_Inchtprops contains the following members: 
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double xunits; 
double yunits; 
double xmax; 

double xmin; 

double ymax; 

double ymin; 
unsigned xdiv; 
unsigned ydiv; 

gi axtype xaxtype; 
gi axtype yaxtype; 
gi_rotation axorient; 
dp bool key; 

dp color scalcol; 

gi Inchtapps *apps; 
dp _ bool joined; 


xunits, yunits, xmax, xmin, ymax, ymin, xdiv, ydiv, axorient, key and scalcol have the same range of 
values as their counterparts in the line chart property sheet. 
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xaxtype and yaxtype are of the type gi_axtype, an enumerated variable that specifies the gauge, or 
grid increments, to be used in generating the line chart. It may have one of the following values: 


AXT NONE /* none */ 

AXT SPLAIN /* single plane */ 
AXT STICK /* single tick */ 
AXT DPLAIN /* double plane */ 
AXT DTICK /* double tick */ 
AXT __DFULL /* double full */ 


axorient is of the type gi_rotation, an enumerated variable that specifies the orientation with which 
the chart and all its elements are to be inserted within the document. It may have one of the following 


values: 
RT NORMAL /* normal */ 
RT 90 /* rotate 90 */ 
RT 1 80 /* rotate 180 */ 
RT 270 /* rotate 270 */ 


key is a Boolean value that, when set to TRUE, displays the explanatory notes in the line chart 


sclcol is of the type dp__color. It is a structure that specifies the color to be used in drawing the line 
chart scale. 


apps is ofthe type gi Inchtapps. It is a structure that specifies the visual attributes of the lines used to 
draw the elements of the line chart itself, such as point size, fill pattern and brush. It contains the 
following members: 


unsigned length; 
gi_Inchtapp *values; 


values is a pointer to an array of gi Inchtapp. It is a structure that contains the following 
members: 


unsigned psize; 

gi ptfill pfill; 

gi ptstyle pstyle; 
dp color pcolor; 

gi curvetype ctype; 


gi_brush cbrush; 


ctype is a structure of the type, gi_curvetype. It may have one of the following values: 


CUT STRAIGHT /* straight */ 

CUT SPLINE /* spline */ 

CUT BESTFIT /* best fit straight */ 
CUT EXP /* exponential */ 


pfill and pstyle are of the type gi__ptfill and gi__ptstyle, respectively. They are described in 
gi_adpoint(). 


joined is a Boolean value that specifies whether the elements of the line chart are to merged as one 
with the line chart, or if they are to remain separate graphic elements. If joined is FALSE, each 
graphics element, such as rectangles and lines, will be independent of the line chart and may be 
manipulated accordingly. 
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data is a pointer of the type gi__chtdat. See gi__adbacht() for a description of gi_chtdat. 


wchild is a Boolean that, when set to TRUE, will cause a handle to the line chart to be returned in ret. After 
which, graphic elements may be added to the handle. When set to FALSE, ret will contain a NULL value and 
the document editor will build the line chart from the information contained in gi chtdat. If a handle is 
returned, gi__finishcht() must be called to release it when done. 


RETURN VALUE 


If the call is successful 0 is returned, otherwise -1 is returned. The function getsigno() is used to get the 
reason for the failure. 


ERRORS 
gi_adincht() will fail if one or more of the following are true: 


Doc DocumentFull No more room in the document. 

Doc ReadonlyDoc Document opened in ReadOnly mode. 

Doc OutOfDiskSpace Not enough disk space for the operation. 

Doc OutOfVM Not enough virtual memory for the operation. 
Doc BadParm One of the arguments specified is invalid. 
Doc_IllegalHandle The specified handle is illegal. 


Doc TimeOut Inter-process communication has exceeded the maximum allowed time. 
SEE ALSO 


gi_adpoint(),gi_adbacht(), gi_finishcht() 
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gi__adpicht 


NAME 
gi__adpicht - add pie chart 


SYNOPSIS 


include “DociCProps.h” 
#include “Graphics!C.h” 


int 
gi adpicht(h, box, props, data, wchild, ret) 
~ gi handleh; 
gi box *box; /* NULL */ 
gi pichtprops *props; /* NULL */ 
gi chtdat *data; 
dp bool wchild; /* FALSE */ 
gi_handle *ret; /* Returned */ 
DESCRIPTION 


The gi_adpicht() function is used to add a pie chart to a specified graphics container. 
See gi__adbacht() for a description of the h and box arguments. 


The props argument is a pointer of the type gi__pichtprops. It is a structure whose members specify the 
properties of the resulting pie chart. gi__pichtprops contains the following members: 


unsigned wth; 

gi piestyle style; 
gi chtapps *apps; 
dp _bool joined; 


wth is the width of lines, specified in units of micas. The standard brush widths may have one of the 
following value: 


GSLW1 /* 1 width for Graphics Single Line */ 
GSLW2 /* 2 width for Graphics Single Line */ 
GSLW3 /* 3 width for Graphics Single Line */ 
GSL W4 /* 4width for Graphics Single Line */ 
GSLW5 /* 5 width for Graphics Single Line */ 
GSL W6 /* 6 width for Graphics Single Line */ 


Each value corresponds to 35, 71, 106, 141, 176, and 212 micas, respectively. Non-standard brush 
widths will result in an error. 


style is a structure of the type gi__piestyle. Its members define how the pieces of the pie chart are to be 
placed with respect to the other pieces. It has the following members: 


PIS _ADJOIN /* adjoining */ 
PIS SEPARAT /* separated */ 
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apps is of the type gi chtapps. It is a structure that specifies the visual attributes of the lines used to 
draw the elements of the pie chart itself, such as fill pattern and shading color. It contains the 
following members: | 


unsigned length; 
gi_chtapp *values; 


values is a pointer to anarray ofgi__chtapp. It is a structure that contains the following members: 


gi__gray gray; 

gi textures txrs; 
dp color txrcol; 
dp color shdcol; 
dp bool tranpare; 
dp_color Incol; 


joined is a Boolean value that specifies whether the elements of the pie chart (e.g., pie slices and text 
frames) are to merged as one with the pie chart, or if they are to remain separate graphic elements. If 
joined is FALSE, each graphics element will remain independent of the line chart and may be 
manipulated accordingly. 


data is a pointer of the type gi_chtdat. Refer to gi_adbacht() for details. 
wchild is a Boolean that, when set to TRUE, will cause a handle to the pie chart to be returned in ret. After 
which, graphic elements may be added to the handle. When set to FALSE, ret will contain a NULL value and 


the document editor will build the pie chart from the information contained in gi__chtdat. If a handle is 
returned, gi__finishcht() must be called to release it when done. 


RETURN VALUE 


If the call is successful 0 is returned, otherwise -1 is returned. The function getsigno() is used to get the 
reason for the failure. 


ERRORS 
gi_adpicht() will fail if one or more of the following are true: 
Doc DocumentFull No more room in the document. 


Doc ReadonlyDoc Document opened in ReadOnly mode. 

Doc OutOfDiskSpace Not enough disk space for the operation. 

Doc OutOfVM Not enough virtual memory for the operation. 
Doc BadParm One of the arguments specified is invalid. 
Doc_IllegalHandle The specified handle is illegal. 


Doc TimeOut Inter-process communication has exceeded the maximum allowed time. 


SEE ALSO 


gi_adbacht(), gi__finishcht() 


3-34 DOCUMENT INTERFACES TOOLKIT SYSTEM REFERENCE 


GRAPHICS IC LIBRARY 


gi__adpislce 


NAME 


gi adpislce - add pie slice 
SYNOPSIS 


#include "GraphicsiC.h” 


int 
gi_adpislce(h, box, props) 
gi_handleh; 
gi box *box; /* NULL */ 
gi_pisiceprops *props; /* NULL */ 
DESCRIPTION 


The gi__adpisice() function is used to place a pie slice in a graphics container. 


The h argument is the graphics container handle returned by an earlier call to gi__startgframe(), 
gi_startgr(),gi__startbtn(), gi__startnbtn(), gi__startcluster(), or gi_adpicht(). 


The box argument is a pointer of the type gi_box. Refer togi__adcurve() for adescription ofgi__box. 


The props argument isa pointer to gi__pislceprops. It is a structure whose members define the appearance 
of the pie slice. gi_pislceprops contains the following members: 


gi brush brsh; 

gi shading shade; 
gi_place center; 
gi place start; 

gi place stop; 

dp bool fixshape; 


brsh is of the type gi brush. It specifies the visual qualities of the lines used to draw the pie slice, such 
as solid or dashed lines, and their color. Refer to the description of gi startgframe() for general 
information regarding brsh. The exception to the description of brsh in gi startgframe() is with 
regards to the stylebrush member. The only two parameters that may be specified are STB INVISIBLE 
and STB_ SOLID. 7 


shade is a structure of type gi__ shading. It is used to define the appearance of the pie slice’s interior. Its 
members are: 


gi__gray gray; 

gi textures txrs; 
dp color txrcol; 
dp_color shdcol; 


gray is of the type gi gray, an enumerated variable that specifies the percentage of black, or 


saturation, to be used in making varying shades of the color gray. Refer to gi _adbacht() for a chart 
illustrating the available shades. 
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txrs is a structure of type gi textures. It specifies the direction in which the texture is drawn in the pie 
slice or the type of texture that is to be placed in the pie slice. For example, textures may be drawn ina 
pie slice with a horizontal, vertical, or diagonal orientation. Also, a type of texture that may be placed 
in the pie slice is a polka dot pattern. gi_textures has the following members: 


dp bool vertical; 
dp bool horizontal; 
dp bool nwse; 

dp bool swne; 
dp__bool polkadot; 


Each variable is a Boolean value. The resulting texture will be the AND of the variables . That is, 
each variable that is set to TRUE will be placed as a texture in the graphic object. 


txrcol is a structure of type dp color. Its members define the color that is to be used in drawing the 
texture, or foreground, of the pie slice’s interior. 


shdcol is a structure of type dp_color. Its members define the color to be used when drawing the 
background of the pie slice’s interior. 


center, start, and stop are values of the structure, gi place. These values define the placement of the pie 
slice in box. The members of gi__ place are: 


int x; 
int y; 


x and y are integers that define an x and y axis location in box. Therefore, all grid locations are 
relative to box.place. center is the tip of the pie slice, or, if the pie were whole it could be considered 
the center of the pie. start and stop are the beginning and ending points on the edge, or circumference, 
of the pie slice. The arc of a pie slice goes from start to stop in a clockwise direction. center, start, and 
stop are all specified in units of micas. As shown below: 





fixshape is a Boolean value that, when set to TRUE, indicates that the aspect ratio of a pie slice will remain 
intact when the user grows or shrinks it. A value of FALSE indicates that the aspect ratio of the pie slice 
will change freely. The value of this argument is always to be set to TRUE when adding pie slices. 


RETURN VALUE 


If the call is successful 0 is returned, otherwise -1 is returned. The function getsigno() is used to get the 
reason for the failure. 
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ERRORS 
gi _adpislce() will fail if one or more of the following are true: 

Doc DocumentFull No more room in the document. 
Doc ReadonlyDoc Document opened in ReadOnly mode. 
Doc OutOfDiskSpace Not enough disk space for the operation. 
Doc OutOfVM Not enough virtual memory for the operation. 
Doc BadParm One of the arguments specified is invalid. 
Doc_IllegalHandle The specified handle is illegal. 


Doc_ TimeOut Inter-process communication has exceeded the maximum allowed time. 
SEE ALSO 


gi_adcu rve(), gi_ad bacht() 
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gi__adpoint 


NAME 
gi__adpoint - add point 


SYNOPSIS 


#include “GraphicsiC.h” 


int 
gi__adpoint(h, box, props) 
gi_handleh; 
gi box *box; /* NULL */ 
gi__pointprops *props; /* NULL */ 
DESCRIPTION 


The gi__adpoint() function is used to add a point of a specific size and shape to a graphics container. 


The h argument is the graphics container handle returned by an earlier call to gi startgframe(), 
gi _startgr(), gi_startbtn(), gi_startnbtn(), gi_startcluster(), or gi_adincht(). 


The box argumentisapointerofthetypegi box. Refer to gi_adcu rve() for a general description of gi_box. 
Note that the value of box.dims may be arbitrary because a point does not have dimensions, and so the 
value entered will be ignored. 7 


The props argument isa pointer to gi__pointprops. It is a structure whose members define the appearance 
of the point. gi_pointprops contains the following members: 


unsigned wth; 

gi ptstyle style; 
gi ptfill fill; 
dp__color color; 


wth is the width of lines, specified in units of micas. The standard brush widths may have one of the 


following value: 
GSLW1 /* 1 width for Graphics Single Line */ 
GSL W2 /* 2 width for Graphics Single Line */ 
GSL W3 /* 3 width for Graphics Single Line */ 
GSL W4 /* 4 width for Graphics Single Line */ 
GSLW5 /* 5 width for Graphics Single Line */ 
GSL W6 /* 6 width for Graphics Single Line */ 


Each value corresponds to 35, 71, 106, 141, 176, and 212 micas, respectively. Non-standard brush 
widths will result in an error. 
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style is of the type gi__ptstyle. It is an enumerated variable that specifies the shape of the point. It may 
have one of the following values: 


PTS ROUND /* round */ 

PTS SQUARE /* square */ 

PTS TRIANGLE /* triangle */ 

PTS CROSS /* cross */ 

PTS INVISIBLE /* invisible */ 

PTS INVISIBLE may only be specified when placing a point in a line chart. This value is illegal in 


every other type of container. 


fill is a structure of type gi_ptfill. It specifies if the point is to be drawn as a solid fill object or as an 
outline object with no fill. One of two values may be specified:PTF_ SOLIDor PTF HOLLOW. 


color is astructure of typedp color. Its members are integers that specify a color that was obtained by 
a color extraction function, such as dp colfromname(). 


RETURN VALUE 


If the call is successful 0 is returned, otherwise -1 is returned. The function getsigno() is used to get the 
reason for the failure. 


ERRORS 


gi_adpoint() will fail if one or more of the following are true: 


Doc DocumentFull No more room in the document. 


Doc ReadonlyDoc Document opened in ReadOnly mode. 


Doc OutOfDiskSpace Not enough disk space for the operation. 


Doc OutOfVM Not enough virtual memory for the operation. 


Doc BadParm One of the arguments specified is invalid. 


Doc_IllegalHandle The specified handle is illegal. 


Doc TimeOut Inter-process communication has exceeded the maximum allowed time. 


SEE ALSO 


dp__colfromname(), gi _adcurve() 


DOCUMENT INTERFACES TOOLKIT SYSTEM REFERENCE 3-39 


GRAPHICS IC LIBRARY 


gi__adrectangle 


NAME 


gi__adrectangle - add rectangle 
SYNOPSIS 


#include “GraphicsiC.h” 


int 
gi_adrectangle(h, box, props) 
gi_handleh; 
gi box *box; 7 /* NULL */ 
gi_rectangleprops *props; /* NULL */ 
DESCRIPTION 


The gi__adrectangle() function is used to add a rectangle of a specific size and shape to a graphics container. 


The h argument is the graphics container handle returned by an earlier call to gi__startgr(), 
gi_startgframe(), gi__cluster(), gi__startnbtn(), gi startbtn(),gi__adbacht(), or gi__adincht(). 


The box argument is a pointer of type gi__box. It defines the size of the rectangle. Refer togi__adcurve() for 
a description of gi box. 


The props argument is a pointer of the type gi_rectangleprops. It is a structure whose members define the 
appearance of the rectangle. Its members are: 


gi__brush brsh; 
gi_ shading shade; 
dp_bool fixshape; 


brsh is a structure that defines the visual qualities of the lines used in tracing the border of the 
rectangle. It contains the following members: 


unsigned wth; 
gi_stlbrush stylebrush; 
dp__color brushcolor; 


wth is the width of lines, specified in units of micas. The standard brush widths may have one of 


the following value: 
GSLW1 /* 1 width for Graphics Single Line */ 
GSL W2 /* 2 width for Graphics Single Line */ 
GSLW3 /* 3 width for Graphics Single Line */ 
GSLW4 /* 4 width for Graphics Single Line */ 
GSLWS5 /* 5 width for Graphics Single Line */ 
GSL W6 /* 6 width for Graphics Single Line */ 


Each value corresponds to 35, 71, 106, 141, 176, and 212 micas, respectively. Non-standard 
brush widths will result in an error. 
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stylebrush defines how the lines are drawn, such as solid or dashed. It may have one of the 
following values: 


STB INVISIBLE /* invisible */ 
STB. SOLID /* solid */ 
STB DASHED /* dashed */ 
STB DOTTED /* dotted */ 
STB DOUBLE /* double */ 
STB BROKEN /* broken */ 


The value of wth is affected by the stylebrush specified. For example, the wth of STB DOUBLE 
borders is 3 times the usual width because it consists of two lines separated by a gap equal to the 
width of the line. 


brushcolor specifies the color to be used to display the lines that make up the edges of the graphic 
object. The value of color may be any color that isa member of dp color. 


shade is a structure of type gi shading. It is used to define the appearance of the rectangle’s interior. 
Its members are: 


gi gray gray; 

gi textures txrs; 
dp color txrcol; 
dp _color shdcol; 


gray is of the type gi gray, an enumerated variable that specifies the percentage of black, or 
saturation, to be used in making varying shades of the color gray. If stylebrush is set to 
STB INVISIBLE, then gray may not be set to GRY NONE, otherwise the rectangle will become 
invisible. Refer to gi_ad bacht() for a chart illustrating the available shades. 


txrs is a structure of type gi textures. It specifies the direction in which the texture is drawn in the 
rectangle or the type of texture that is to be placed in the rectangle. For example, textures may be 
placed in an rectangle with a horizontal, vertical, or diagonal orientation. Also, a type of texture 
that may be placed in the rectangle is a polka dot pattern. gi_textures has the following members: 


dp bool vertical; 
dp bool horizontal; 
dp bool nwse; 

dp bool swne; 

dp __bool polkadot; 


Each variable is a Boolean value. The resulting texture will be the AND of the variables . 
That is, each variable that is set to TRUE will be placed as a texture in the graphic object. 


txrcol is a structure of type dp__color. Its members define the color that is to be used in drawing the 
texture, or foreground, of the rectangle’s interior. 


shdcol is a structure of type dp_color. Its members define the color to be used when drawing the 
background in the rectangle’s interior. This parameter is enabled only when the value of gray is 
GRY GRAY. If the value of gray is any other value, shdcol is set to black{0, 0, O}. 


fixshape is a Boolean value that, when set to TRUE, indicates that the aspect ratio of the rectangle will 


remain intact when the user grows or shrinks it. A value of FALSE indicates that the aspect ratio of the 
rectangle will change freely. 
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RETURN VALUE 


If the call is successful 0 is returned, otherwise -1 is returned. The function getsigno() is used to get the 
reason for the failure. 


ERRORS 


gi_ad rectangle() will fail if one or more of the following are true: 
Doc DocumentFull No more room in the document. 
Doc ReadonlyDoc Document opened in ReadOnly mode. 
Doc OutOfDiskSpace Not enough disk space for the operation. 


Doc OutOfVM Not enough virtual memory for the operation. 

Doc BadParm One of the arguments specified is invalid. 

Doc IllegalHandle The specified handle is illegal. 

Doc TimeOut Inter-process communication has exceeded the maximum allowed time. 
SEE ALSO 


gi_adcurve(), gi__adbacht() 
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gi__adtable 


NAME 
gi__adtable - add table 


SYNOPSIS 


#include “DoclCProps.h” 
#include “GraphicsiC.h” 


int 
gi adtable(h, box, table, frprops, fixwidth, fixheight, wtcap, wbcap, wicap, wrcap, ret) 
~ gi handleh; 
gi box *box; /* NULL */ 
di ins table; /* NULL */ 
gi frameprops *frprops; /* NULL */ 
dp bool fixwidth; /* FALSE */ 
dp bool fixheight; /* FALSE */ 
dp bool wtcap; /* FALSE */ 
dp bool wbcap; /* FALSE */ 
dp bool wicap; /* FALSE */ 
dp bool wrcap; /* FALSE */ 
ret__adtable *ret; /* Returned */ 
DESCRIPTION 


The gi__adtable() function is used to add a table frame into a graphics container. 


The h argument is the graphics container handle returned by an earlier call to gi_ startgr(), 
gi__startgframe(), gi__startbtn(), gi_startnbtn(), or gi__startcluster(). 


Refer to the description of box in gi_adffield() for more information on box. Refer to gi_ sta rtgframe() fora 
description of the *frprops, and w*cap arguments. 


The table argument is of the type di__ins. It isan opaque variable that contains the table handle that was 
returned by an earlier call to ti__finishtable(). 


fixwidth and fixheight are Boolean values that indicate whether the width and/or height of a table frame 
is to remain static. 


The gi_adtable() function sets the return information into the structure ret__adtable, which contains the 
following members: 


di caption tcap; 
di caption bcap; 
di caption Icap; 
di caption rcap; 


The *cap arguments are each of the type di caption, an opaque variable that contains a caption 


handle for the top, bottom, left, and right edges of the table frame, respectively. These handles may 
then be passed to various di_a p*() functions to append captions to the table. 
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RETURN VALUE 


If the call is successful 0 is returned, otherwise -1 is returned. The function getsigno() is used to get the 
reason for the failure. 


ERRORS 


gi _adtable() will fail if one or more of the following are true: 
Doc Docu mentFull No more room in the document. 
Doc ReadonlyDoc Document opened in ReadOnly mode. 


Doc OutOfDiskSpace Not enough disk space for the operation. 


Doc OutOfVM Not enough virtual memory for the operation. 

Doc BadParm One of the arguments specified is invalid. 

Doc_IllegalHandle The specified handle is illegal. 

Doc TimeOut Inter-process communication has exceeded the maximum allowed time. 
SEE ALSO 


ti__finishtable(), gi__adffield(), gi__startgframe() 
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gi__adtframe 


NAME 


gi__adtframe - add text frame 
SYNOPSIS 


#include “DociCProps.h” 
#include “GraphicsiC.h” 


int 
gi adtframe(h, box, frprops, tfprops, wtext, wtcap, wbcap, wicap, wrcap, ret) 
~ gi handle h; 
gi box *box; /* NULL */ 
gi frameprops *frprops; /* NULL */ 
gi tframeprops *tfprops; /* NULL */ 
dp bool wtext; /* FALSE */ 
dp bool wtcap; /* FALSE */ 
dp bool wbcap; /* FALSE */ 
dp bool wicap; /* FALSE */ 
dp bool wrcap; /* FALSE */ 
ret__adtframe *ret; /* Returned */ 
DESCRIPTION 


The gi__adtframe() function is used to add a text frame to a specified graphics container. 


The h argument is the graphics container handle returned by an earlier call to gi startgr(), 
gi_startgframe(), gi__startbtn(),gi_startnbtn(), gi startcluster(), gi_adbacht(), gi_adincht(), gi_adpicht(). 


Refer to the description of box in gi__adffield for more information on box. Refer to gi__startgframe() for a 
description of the *frprops and w*cap arguments. Refer to gi__adffield() for a description of tfprops. 


The wtext argument is a Boolean value that specifies whether or not the frame is to have text. If a value of 
TRUE is specified, the text variable in the return value will be non-NULL. DociC functions may then be used 
to add the text. Note the text must eventually be freed by acalltodi__reltext(). 


The gi__adtframe() function sets the return information into the structure ret__adtframe, which contains 
the following members: 


di_text text; 

di__caption tcap; 

di__caption bcap; 

di caption Icap; 

di__caption recap; 

Refer to gi_adffield() for a description of *cap. 
RETURN VALUE 


If the call is successful 0 is returned, otherwise -1 is returned. The function getsigno() is used to get the 
reason for the failure. 
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ERRORS 


gi__adtframe() will fail if one or more of the following are true: 
Doc DocumentFull No more room in the document. 
Doc ReadonlyDoc Document opened in ReadOnly mode. 
Doc OutOfDiskSpace Not enough disk space for the operation. 
Doc OutOfVM Not enough virtual memory for the operation. | 
Doc _BadParm One of the arguments specified is invalid. 
Doc_illegalHandle The specified handle is illegal. 


Doc_ TimeOut Inter-process communication has exceeded the maximum allowed time. 
SEE ALSO 


gi__adffield(),gi_startgframe(),di__reltext() 
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gi__adtriangle 


NAME 


gi__adtriangle - add triangle 


SYNOPSIS 


#include “GraphicsiC.h” 


int 
gi__adtriangle(h, box, props) 
gi_handleh; 
gi box *box; /* NULL */ 
gi_triangleprops *props; /* NULL */ 
DESCRIPTION 


The gi_adtriangle() function is used to add a triangle of a specific size to a graphics container. 


The h argument is the graphics container handle returned by an earlier call to gi_startgr(), 
gi_startgframe(), gi__startbtn(), gi__startnbtn(), or gi__startcluster(). 


The box argument is a pointer of the type gi box. Its two members, place and dims. specify the origin of 
the area in which the triangle will be placed and its size, relative to the graphics container. Refer to 
gi_adcurve() for a description of gi_box. 


The props argument is a pointer to gi__triangleprops, a structure whose members define the appearance 
of the triangle. It contains the following members: 


gi brush brsh; 

gi shading shade; 
gi place p1; 

gi place p2; 

gi place p3; 


dp _bool fixshape; 


brsh is a structure that defines the visual qualities of the lines used in tracing the border of the 
triangle. It contains the following members: 


unsigned wth; 
gi_stibrush stylebrush; 
dp_color brushcolor; 


wth is the width of lines, specified in units of micas. The standard brush widths may have one of 
the following value: 


GSLWY1 /* 1 width for Graphics Single Line */ 
GSLW2 /* 2 width for Graphics Single Line */ 
GSL W3 /* 3 width for Graphics Single Line */ 
GSL W4 /* 4 width for Graphics Single Line */ 
GSLW5 /* 5 width for Graphics Single Line */ 


GSL W6 /* 6 width for Graphics Single Line */ 
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Each value corresponds to 35, 71, 106, 141, 176, and 212 micas, respectively. Non-standard 
brush widths will result in an error. 


stylebrush defines how the lines are drawn, such as solid or dashed. It may have one of the 


following values: 
STB. INVISIBLE /* invisible */ 
STB SOLID /* solid */ 
STB DASHED /* dashed */ 
STB DOTTED /* dotted */ 
STB DOUBLE /* double */ 
STB BROKEN /* broken */ 


The value of wth is affected by the stylebrush specified. For example, the wth of STB DOUBLE 
borders is 3 times the usual width because it consists of two lines separated by a gap equal to the 
width of the line. 


brushcolor specifies the color to be used to display the lines that make up the edges of the graphic 
object. The value of color may be any color that isa member of dp ___color. 


shade is a structure of type gi__shading. It is used to define the appearance of the triangle’s interior. Its 
members are: 


gi gray gray; 

gi textures txrs; 
dp color txrcol; 

dp _color shdcol; 


gray is of the type gi! gray, an enumerated variable that specifies the percentage of black, or 
saturation, to be used in making varying shades of the color gray. If stylebrush is set 
STB INVISIBLE, then gray may not be set to GRY NONE, otherwise the triangle will become 
invisible. Refer to gi_adbacht() for a chart illustrating the available shades. 


txrs is a structure of type gi textures. It specifies the direction in which the texture is drawn in the 
triangle or the type of texture that is to be placed in the triangle. For example, textures may be 
placed in an triangle with a horizontal, vertical, or diagonal orientation. Also, a type of texture 
that may be placed in the triangle is a polka dot pattern. gi__ textures has the following members: 


dp bool vertical; 
dp bool horizontal; 
dp bool nwse; 

dp bool swne; 

dp _bool polkadot; 


Each variable is a Boolean value. The resulting texture will be the AND of the variables . 
That is, each variable that is set to TRUE will be placed as a texture in the graphic object. 


txrcol is astructure of typedp color. Its members define the color that is to be used in drawing the 
texture, or foreground, of the triangle’s interior. 


shdcol is a structure of type dp__color. Its members define the color to be used when drawing the 
background in the triangle’s interior. This parameter is enabled only when the value of gray is 
GRY BLACK. If the value of gray is any other value, shdcol is set to black {0, 0, 0}. 


p1, p2, and p3 are of the type gi__ place. As mentioned in the description of box, gi__ place is a structure 
that contains two integer members, x and y. When adding a triangle, these three members specify the 
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the x and y grid location for each of the three points of the triangle. p1, p2, and p3 are specified in 
units of micas. 


fixshape is a Boolean value that, when set to TRUE, indicates that the aspect ratio of a triangle will remain 
intact when the user grows or shrinks it. A value of FALSE indicates that the aspect ratio of the triangle 
will change freely. 


RETURN VALUE 


If the call is successful 0 is returned, otherwise -1 is returned. The function getsigno() is used to get the 
reason for the failure. 
ERRORS 
gi _adtriangle() will fail if one or more of the following are true: 
Doc DocumentFull No more room in the document. 
Doc ReadonlyDoc Document opened in ReadOnly mode. 


Doc OutOfDiskSpace Not enough disk space for the operation. 


Doc OutOfVM Not enough virtual memory for the operation. 

Doc BadParm One of the arguments specified is invalid. 

Doc IllegalHandle The specified handle is illegal. 

Doc_ TimeOut Inter-process communication has exceeded the maximum allowed time. 
SEE ALSO 


gi_adcurve(), gi_adbacht() 
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gi__ap*btnprog 


NAME 


gi__apchartobtnprog, gi__apnparatobtnprog, gi__aptexttobtnprog - add toa CUSP button 


SYNOPSIS 


#include “DociCProps.h” 
#include “GraphicsiC.h” 
#include “XString.h” 


int 


gi _apchartobtnprog(to, char, foprops, num) 


int 


gi buttonprog to; 


XChar char; 
dp fontprops *foprops; /* NULL */ 
unsigned num; iV] 


gi_apnparatobtnprog(to, paprops, foprops, num) 


int 


gi_buttonprog to; 


dp _paraprops *paprops; /* NULL */ 
dp fontprops *foprops; /* NULL */ 
unsigned num; aie Veal | 


gi _aptexttobtnprog(to, text, foprops) 


gi__buttonprog to; 
XString text; 


dp__fontprops *foprops; /* NULL */ 


DESCRIPTION 


3-50 


The following functions allow the user to add textual information to a CUSP button program. 


gi_apchartobtnprog() is used to add a character to the button program. 


gi_apnparatobtnprog() adds a new paragraph character with specified properties to the button program. 


gi_aptexttobtnprog() adds a string with specified properties to button program. 


For all three functions: 


to is the button handle returned by an earlier call to gi_ sta rtbtn() or gi_ sta rtnbtn(). 


char and text are the respective character and text strings to be inserted in the button program. 


Refer todp__paraprops and dp__fontprops in dp _ props for a description of foprops and paprops. 


num is the number of copies of the character or new paragraph characters to be added. 


DOCUMENT INTERFACES TOOLKIT SYSTEM REFERENCE 


GRAPHICS IC LIBRARY 


RETURN VALUE 


If the call is successful 0 is returned, otherwise -1 is returned. The function getsigno() is used to get the 


reason for the failure. 
ERRORS 


gi_ap*btnprog() will fail if one or more of the following are true: 
Doc DocumentFull No more room in the document. 
Doc ReadonlyDoc Document opened in ReadOnly mode. 
Doc OutOfDiskSpace Not enough disk space for the operation. 
Doc OutOfVM Not enough virtual memory for the operation. 
Doc BadParm One of the arguments specified is invalid. 


Doc _ IllegalHandle The specified handle is illegal. 


Doc TimeOut Inter-process communication has exceeded the maximum allowed time. 


SEE ALSO 


gi_startbtn(),gi__startnbtn() 
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gi__btnforaframe 


NAME 


gi__btnforaframe - button info for anchored frame 


SYNOPSIS 


#include “DociC.h” 
#include “GraphicsIC.h” 
#include “XString.h” 


int 
gi btnforaframe(aframe, props, gridprops, ret) 
~ di ins aframe; 
XString *props; 
gi gridprops *gridprops; 
gi_buttonprog *ret; /* Returned */ 


DESCRIPTION 


The gi btnforaframe() function is used to extract the properties of a button in an anchored CUSP button 
frame during enumeration. The button handle that is returned, gi buttonprog, is a text object that points 
to CUSP programming code. It may be passed as an argument to enumbtnprog() to enumerate the text 
within the button. 


The aframe argument is of the type di__ins, an enumerated variable that contains the handle of the frame 
in question. It was obtained by an earlier call to one of the di__enumerate() call-back procedures 
(di__aframeproc()). 


The props argument is a pointer of the type XString. It is a return value in which the properties of a 
button are returned. 


The gridprops argument is a pointer of the type gi__gridprops. It is a return value in which the grid 
properties of an anchored button are returned. | | 


The ret argument is a pointer of the type gi buttonprog, a handle to the button program object that 
contains the text contents of the anchored CUSP button. 


RETURN VALUE 


If the call is successful 0 is returned, otherwise -1 is returned. The function getsigno() is used to get the 
reason for the failure. 


ERRORS 


gi_btnforaframe() will fail if one or more of the following are true: 
Doc BadParm One of the arguments specified is invalid. 
Doc _IllegalHandle The specified handle is illegal. 


Doc TimeOut Inter-process communication has exceeded the maximum allowed time. 


SEE ALSO 


di_enumerate(), gi_enumbtnprog() 
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gi__enumbtnprog 
NAME 

gi__enumgbtnprog - enumerate button program 
SYNOPSIS 

#include “GraphicsiIC.h” 

int 

gi _enumbtnprog(prog, procs, cdat. ret) 


gi_buttonprog prog; 
gi btnenumprocs * procs; 


void *cdat; /* NULL */ 
dp__bool *ret; /* Returned */ 
DESCRIPTION 


The gi_enumbtnprog() function is used to enumerate the properties and text contents of a CUSP button. 
prog is a variable of the type gi_buttonprog. Refer togi__startnbtn() for a description of gi__buttonprog. 


procs is a pointer of the type gi btnenumprocs, a user-supplied structure containing the user’s call-back 
procedures. gi__btnenumprocs contains the following members: 


di newparaproc *newpara; 
di_textproc *text; 


newpara is a pointer of the type di mewparaproc, a call-back procedure that is called when a new 
paragraph character is encountered in the text. 


text is a pointer of the type di textproc, a call-back procedure that is called whenever a substring of 
text is encountered. The whole substring is passed as a parameter. Therefore, di__textproc may be 
called repeatedly, once for each substring of text having the same properties. 


cdat is passed to each call-back procedure during enumeration. 


ret will be true if gi enumbtnprog() encounters an object it does not recognize, or an object for which a 
call-back procedure was not supplied. 


RETURN VALUE 


If the call is successful 0 is returned, otherwise -1 is returned. The function getsigno() is used to get the 
reason for the failure. 
ERRORS | 
gi__enumbtnprog() will fail if one or more of the following are true: 
Doc BadParm One of the arguments specified is invalid. 
Doc_IllegalHandle The specified handle is illegal. 


Doc TimeOut Inter-process communication has exceeded the maximum allowed time. 
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SEE ALSO 


gi__btnforaframe(), gi_enumerate() 
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gi__ enumerate 
gi__enumerate - reading graphics 
SYNOPSIS 


#include “DociC.h” 
#include “GraphicsiC.h” 


int 


gi enumerate(gcont, procs, cdat. ret) 


di ins gcont; 

gi enumprocs *procs; 
void *cdat; 

dp_bool *ret; 


CALLBACK PROCEDURE 


dp bool 


/* NULL */ 
/* Returned */ 


gi__bachtproc(cdat, box, props, data, chart) 


void *cdat; 

gi box *box; 

gi bachtprops *props; 
gi chtdat *data; 

di ins chart; 


dp bool 


gi bmproc(cdat, box, bmprops, frprops) 


~ void *cdat; 
gi box *box; 
gi bmprops *bmprops; 
gi__frameprops *frprops; 


dp bool 


gi buttonproc(cdat, gcont, box, name, gridprops, frprops, prog) 


~ void *cdat; 
di ins gcont; 
gi box *box; 
XString name; 
gi gridprops *gridprops; 
gi frameprops *frprops; 
gi__buttonprog prog; 


dp__bool 
gi_clusterproc(cdat, gcont, box) 
void *cdat; 


di_ins gcont; 
gi__box *box; 


dp_bool 
gi_curveproc(cdat, box, props) 
void *cdat; 


gi_box *box; 
gi_curveprops *props; 
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dp bool 
gi ellipseproc(cdat, box, props) 
~ void *cdat; 
gi box *box; 
gi__ellipseprops *props; 


dp bool 
gi tfieldproc(cdat, box, fiprops, frprops, tfprops, paprops, foprops, cont) 
~ void *cdat; 
gi box *box; 
dp fidprops *fiprops; 
gi trameprops *frprops; 
gi tframeprops *tfprops; 
dp paraprops *paprops; 
dp fontprops *foprops; 
di_ field cont; 


dp bool 
gi frameproc(cdat, gcont, box, frprops, gfprops) 
~ void *cdat; 
di ins gcont; 
gi box *box; 
gi frameprops *frprops; 
gi__gframeprops *gfprops; 


dp bool 
gi Inchtproc(cdat, box, props, data, chart) 
~ void *cdat; 
gi box *box; 
gi Inchtprops *props; 
gi chtdat *data; 
di_ins chart; 


dp bool 
gi Tineproc(cdat, box, props) 
~ void *cdat; 
gi box *box; 
gi_lineprops *props; 


dp bool 
gi pichtproc(cdat, box, props, data, chart) 
~ void *cdat; 
gi box *box; 
gi pichtprops *props; 
gi chtdat *data; 
di_ins chart; 


dp__bool 
gi_pislceproc(cdat, box, props) 
void *cdat; 


gi__box *box; 
gi_pisiceprops *props; 
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dp_bool 
gi_pointproc(cdat, box, props) 
void *cdat; 


gi_ box *box; 
gi_pointprops *props; 


dp_bool 
gi_rectangleproc(cdat, box, props) 
void *cdat; 


gi_box *box; 
gi_rectangleprops *props; 


dp_bool 
gi _tableproc(cdat, box, table, frprops, fixwidth, fixheight) 
void *cdat; 


gi box *box; 
di_ins table; 
gi frameprops *frprops; 


dp _ bool fixwidth; /* FALSE */ 
dp_bool fixheight; /* FALSE */ 
dp__bool 
gi_tframeproc(cdat, box, frprops, tfprops, cont) 
void *cdat; 


gi box *box; 
gi frameprops *frprops; 
gi tframeprops *tfprops; 
di__text cont; 


dp boolgi triangleproc(cdat, box, props) 
~ void *cdat; 
gi box *box; 
gi_triangleprops *props; 


DESCRIPTION 


The gi enumerate() function is used to read the contents of a graphics frame. It takes a graphics 
container handle, a list of call-back procedures, and user data as arguments. Typically, a call-back 
procedure is supplied for each type of graphic object that is in the graphics container. Once called, 
gi enumerate() proceeds through each container, calling the appropriate procedure for each type of object 
encountered. 


Each call-back procedure takes arguments that describe the properties of the object in question. These 
properties are temporary, and will be invalidated upon completion of the procedure call. If you want to 
save these properties, you must explicitly copy them. 


gi_rel* functions should not be called by any of the gi enumerate() call-back procedures because the 
handles for each gi_rel* function is automatically released once it has been processed. 


In the case of a CUSP button, a cluster, or a nested graphics frame, gi _enumerate() may be called 
recursively to extract the contents of nested frames. 
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gi enumprocs contains the following members: 


gi 
gi 
gi 
gi 
gi 
gi 
gi 
gi 
gi 
gi 
gi 
gi 
gi 
gi 
gi 
gi 
gi 


bachtproc *bacht; 
~ bmproc *bm; 
~ buttonproc *button; 
~ clusterproc *cluster; 
~ Curveproc *curve; 
~ ellipseproc *ellipse; 
~ ffieldproc *ffield; 
~ frameproc *frame; 
~ Inchtproc *Incht; 
~ lineproc *line; 
~ pichtproc *picht; 
~ pisiceproc *pisice; 
~ pointproc *point; 
~ rectangleproc *rectangle; 
~_tableproc *table; 


__tframeproc *tframe; 
__triangleproc *triangle; 


Related enumeration functions are di _enumerate() and gi enumbtn prog(). They are used to enumerate 
the contents of a document or text container and a CUSP button, respectively. 


ret will be TRUE if gi_enumerate() encounters an object it does not recognize, or an object for which a call- 
back procedure was not supplied. 


RETURN VALUE 


If the 


call is successful 0 is returned, otherwise -1 is returned. The function getsigno() is used to get the 


reason for the failure. 


ERRORS 


gi_enumerate() will fail if one or more of the following are true: 


Doc BadParm One of the arguments specified is invalid. 

Doc_IllegalHandle The specified handle is illegal. 

Doc TimeOut Inter-process communication has exceeded the maximum allowed time. 
SEE ALSO 


di _enumerate(), gi enumbtnprog() 


DOCUMENT INTERFACES TOOLKIT SYSTEM REFERENCE 


GRAPHICS IC LIBRARY 


gi__finish* 


NAME 


gi__finishnbtn, gi__finishcluster, gi__finishgr, gi__finishframe, gi__finishcht - finish routine 
SYNOPSIS 


#include “DociC.h” 
#include “GraphicsiC.h” 


int 
gi_finishcht(chart) 


gi_handle chart; 


int 
gi finishcluster(ch) 


gi handle ch; 


int 
gi finishgframe(gfh) 
~ gi__handle gfh; 
int 
gi finishgr(h, ret) 
~ gi handle h; 
di_ins *ret; /* Returned */ 


int 

gi_finishnbtn(bfh) 
gi_handle bfh; 

DESCRIPTION 


The gi__finish*() functions are used to signal that no more objects are to be added to the respective graphics 
container. Calling agi__finish*() function will free up the respective handle. 


bfh, ch, h, and gfh arguments are the handles obtained from corresponding gi_start*() functions. The 
chart argumentisobtainedfromgi adbacht(),gi adlincht()orgi adpicht() functions when wchild is set to 
TRUE. _ — _ 


gi_finishgr() returns di__ins. Typically, di__ins is passed as an argument todi__apaframe(). 
RETURN VALUE 


If the call is successful 0 is returned, otherwise -1 is returned. The function getsigno() is used to get the 
reason for the failure. 


ERRORS 


gi_finish() will fail if one or more of the following are true: 
Doc_IllegalHandie The specified handle is illegal. 


Doc TimeOut Inter-process communication has exceeded the maximum allowed time. 
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SEE ALSO 


gi start*(),di__apaframe(), gi adbacht(), gi _adincht(), gi_adpicht() 
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gi__getgframeprops 
NAME 

gi__getgframeprops - get graphics frame props 
SYNOPSIS 


#include “DociC.h” 
#include “GraphicsiC.h” 


int 
gi_getgframeprops(aframe, ret) 
di_ins aframe; 
gi_gframeprops *ret; /* Returned */ 
DESCRIPTION 


The gi__getgframeprops() function is used to retrieve the name, description, and grid properties of an 
anchored graphics frame. 


The aframe argument is of the type di_ins, an enumerated variable that contains the handle of the 
anchored frame in question. 


The requested property values are stored in ret. It is a structure that contains the following members: 


XString name; 
XString desc; 
gi_gridprops gridprops; 


name is name of an anchored graphics frame. desc is description of an anchored graphics frame. Refer 
gi_setgframeprops() for a description of gi__gridprops. 


RETURN VALUE 


If the call is successful 0 is returned, otherwise -1 is returned. The function getsigno() is used to get the 
reason for the failure. 


ERRORS 


gi_getgframeprops() will fail if one or more of the following are true: 


Doc BadParm One of the arguments specified is invalid. 

Doc _IllegalHandle The specified handle is illegal. 

Doc TimeOut Inter-process communication has exceeded the maximum allowed time. 
SEE ALSO 


di _enumerate() 
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gi__get*def 
NAME 

gi__get* - get default properties 
SYNOPSIS 


#include “GraphicsiC.h” 


int 
gi_getbachtpropsdef(props) 

gi_bachtprops *props; /* Returned */ 
int 
gi_getbmdispdef(disp) 

gi_bmdisp *disp; /* Returned */ 
int 
gi__getbmpropsdef(props) 

gi__bmprops *props; /* Returned */ 
int 
gi__getbmscalpropsdef(props) 

gi__bmscalprops *props; /* Returned */ 
int 
gi_getboxdef(box) 

gi_box *box; /* Returned */ 
int 
gi_getchtappdef(app) 

gi_chtapp *app; /* Returned */ 
int 
gi_getchtdatdef(dat) 

gi_chtdat *dat; /* Returned */ 
int 
gi_getcurvepropsdef(props) 

gi_curveprops *props; /* Returned */ 
int 
gi_getellipsepropsdef(props) 

gi_ellipseprops *props; /* Returned */ 
gi__getframepropsdef(props) 

gi__frameprops *props; /* Returned */ 
int 
gi_getgframepropsdef(props) | 

gi__gframeprops *props; /* Returned */ 
int 


gi_getgridpropsdef(props) 
gi_gridprops *props; /* Returned */ 
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int 


gi__getlinepropsdef(props) 


int 
gi 


gi_lineprops *props; 


getinchtappdef(app) 


int 


gi_Inchtapp *app; 


gi_getinchtpropsdef(props) 


int 


gi_Inchtprops *props; 


gi__getpichtpropsdef(props) 


int 


gi_pichtprops “props; 


gi_getpislcepropsdef(props) 


int 


gi_pisiceprops *props; 


gi_getpointpropsdef(props) 


int 


gi_getrectanglepropsdef(props) 


int 


gi__pointprops *props; 


gi_rectangleprops *props; 


gi_gettframepropsdef(props) 


int 


gi_gettrianglepropsdef(props) 


gi_tframeprops *props; 


gi_triangleprops *props; 


DESCRIPTION 


/* Returned */ 


/* Returned */ 


/* Returned */ 


/* Returned */ 


/* Returned */ 


/* Returned */ 


/* Returned */ 


/* Returned */ 


/* Returned */ 
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The following functions all return the default values of their respective properties. The properties that are 
returned may be modified individually and then passed in a call to a suitable function to set the properties 


of an object. The actual default values for the properties are shown as C comments. 
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The gi_getbachtpropsdef() function is used to return the default bar chart properties. 


double units; 
unsigned div; 

gi _barscale scale; 
dp color sclcol; 

gi balayout layout; 
gi baspacing spacing; 
gi baorient orient; 
dp bool key; 

dp bool bafloat; 
dp bool mirror; 

gi chtapps *apps; 
dp__bool joined; 


/* 1.0 */ 

/*0*/ 

/*BS STICK (single tick) */ 
/* 0, 0, 0 */ 

/*BL STACKED */ 

/* BSP HALF (half spacing) */ 
/* BO VER (vertical) */ 

/* FALSE */ 

/* FALSE */ 

/* FALSE */ 

/* NULL */ 

/* TRUE */ 


The gi__getbmdispdef() function is used to return the default bitmap display properties. 


enum { 
BM INTERNAL, 
BM_ FILE 
} type; 

union { 
gi bmdat *bm; 
XString name; 


}u; 


/* BM__FILE */ 


/* NULL */ 


The gi__getbmpropsdef() function is used to return the default bitmap properties. 


int xoffset; 

int yoffset; 

XString prntfile; 

gi bmdisp dispsou; 


gi bmscalprops scalprops; 


dp bool remotefile: 
dp__color bitcol; 


The gi_getbmscalpropsdef() function is used to return the default bitmap scale properties. 


enum { 
BMS PRNTRES, 
BMS FIXED, 
BMS AUTOMATIC, 
} type; 
union { 
unsigned res; 
gi scalfix fixed; 
enum { 
SHP SIMILAR, 
SHP FILLUP 
} shape; 
}u; 


/* 0 */ 

/* 0 */ 

/* NULL */ 

/*seegi bmdispdef() */ 

/* see gi bmscalpropsdef() */ 
/* FALSE */ 

/*CL__ BLACK */ 


/* BMS _AUTOMATIC */ 


[* SHP_ SIMILAR */ 


The gi__getboxdef() function is used to return the default box properties. 


gi_place place; 
gi_dims dims; 
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/* 1000, 1000 */ 
/* 1000, 1000 */ 
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The gi_getchtappdef() function is used to return the default chart appearances properties. 


gi gray gray; /* GRY NONE */ 
gi textures txrs; /* all FALSE */ 
dp color txrcol; /* 0,0, 0 */ 

dp color shdcol; /* 0,0, 0 */ 

dp color Incol; /* 0,0, 0 */ 


The gi _getchtdatdef() function is used to return the default chart data properties. 


XString title; /* NULL */ 

gi dataset datset; /*DAS COLUMN */ 

dp lang lang; /* LANG USE (USEnglish) */ 
gi datsource datsou; /* DTS PS,TFO BYCOL */ 
gi labels *collabl; /* NULL */ a 

gi labels *rowlabl; /* NULL */ 

gi_datvalues *values; /* NULL */ 


The gi__getcurvepropsdef() function is used to return the default curve properties. 


gi brush brsh; /*71,STB SOLID, 0, 0, 0 */ 
gi Inend Inenw; /*LE SQUARE */ 
gi _Inend Inese; /* LE SQUARE */ 
gi Inedhd Inhnw; /*LEH NONE */ 
gi Inedhd Inhse; /*LEH NONE */ 
gi place pinw; /* 1000, 0 */ 

gi place plapx; /* 0,0 */ 

gi__ place plse; /* 0, 1000 */ 

gi place plpek; /* 0,0 */ 

dp bool eccentric; /* TRUE */ 
unsigned eccentricity; /* 32768 */ 

dp__ bool fixangle; /* FALSE */ 


The gi__getellipsepropsdef() function is used to return the default ellipse properties. 


gi_brush brsh; /* 71, STB SOLID, {0, 0,0} */ 
gi shading shade; /* GRY NONE, all FALSE, {0, 0,0}, {10000, 0, 0} */ 
dp __ bool fixshape; /* FALSE */ 


The gi_getframepropsdef() function is used to return the default frame properties. 


gi brush brsh; /*71,STB SOLID, {0, 0,0} */ 
dp bool fixshape; /* FALSE *7— 

unsigned mgns[4]; /* 0,0, 0, 0 */ 

di caption capcont[4]; /* NULL, NULL, NULL, NULL */ 
dp color bgcol:; /* 10000, 0, 0 */ 

dp bool tranpare; /* FALSE */ 


The gi__getgframepropsdef() function is used to return the default graphics frame properties. 


XString name; /* NULL */ 
XString desc; /* NULL */ 
gi_gridprops gridprops; /*seegi__bmscalpropsdef() */ 
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The gi__getgridpropsdef() is used to return the default grid properties. 


dp bool act; 

gi gridstyle style; 
gi gridsize size; 
gi place offset; 


/* FALSE */ 
/*GRD DOT */ 
/* GRD 8P */ 
/* 0,0 *7 


The gi __getlinepropsdef() function is used to return the default line properties. 


gi brush brsh; 


gi Inend Inenw; 
gi Inend Inese; 
gi Inedhd Inhnw; 
gi_Inedhd Inhse; 


gi_Indirct dirct; 
dp_bool fixangle; 


/*71,STB SOLID, {0, 0, 0} */ 
/* LE SQUARE */ 

/* LE SQUARE */ 

/* LEH NONE */ 

/* LEH NONE */ 

/*LD WE */ 

/* FALSE */ 


The gi__getinchtappdef() function is used to return the default line chart appearances properties. 


unsigned psize; 

gi ptfill pfill; 

gi ptstyle pstyle; 
dp color pcolor; 

gi curvetype ctype; 
gi_brush cbrush; 


/* 3 */ 

/* PTF SOLID */ 

/* PTS ROUND */ 

/* 0,0, 0 */ 

/* CUT STRAIGHT */ 
/*71,STB_ SOLID, {0, 0, 0} */ 


The gi__getinchtpropsdef() function is used to return the default line chart properties. 


double xunits; 
double yunits; 
double xmax; 
double xmin; 

double ymax; 
double ymin; 
unsigned xdiv; 
unsigned ydiv; 

gi axtype xaxtype; 
gi axtype yaxtype; 
gi rotation axorient; 
dp bool key; 

dp color scalcol; 

gi Inchtapps *apps; 
dp _ bool joined; 


/* 1.0 */ 

/* 1.0 */ 

/* 0.0 */ 

/* 0.0 */ 

/* 0.0 */ 

/* 0.0 */ 

PPO *! 

/*0*/ 

/* AXT STICK (single tick) */ 
/* AXT STICK (single tick) */ 
/* RT NORMAL */ 

/* FALSE */ 

/* 0,0, 0 */ 

/* NULL */ 

/* TRUE */ 


The gi__getpichtpropsdef() function is used to return the default pie chart properties. 


unsigned wth; 

gi piestyle style; 
gi chtapps *apps; 
dp_ bool joined; 


/* 71 */ 

/* PIS ADJOIN */ 
/* NULL */ 

/* TRUE */ 
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The gi__getpisicepropsdef() function is used to return the default pie slice properties. 


gi brush brsh; /*71,STB SOLID, {0, 0, 0} */ 

gi shading shade; /*GRY NONE, all FALSE, {0, 0, 0}, {0, 0, 0} */ 
gi place center; /* 500, 500 */ 

gi place start; /* 500, 0 */ 

gi place stop; /* 0, 500 */ 

dp__bool fixshape; /* FALSE */ 


The gi__getpointpropsdef() function is used to return the default point properties. 


unsigned wth; /* 71 */ 

gi ptstyle style; /*PTS ROUND */ 
gi ptfill fill; /* PTF SOLID */ 
dp__color color; /* 0,0, 0 */ 


The gi__getrectanglepropsdef() function is used to return the default rectangle properties. 


gi_brush brsh; /*71,STB SOLID, {0, 0, 0} */ | 
gi_shading shade; /* GRY NONE, all FALSE, {0, 0, 0}, {0, 0, 0} */ 
dp __ bool fixshape; /* FALSE */ 


The gi _gettframepropsdef() function is used to return the default text frame properties. 


dp_bool expr; /* FALSE */ 
dp_bool expb; /* FALSE */ 
dp _tframeprops props; /* see dp__tframepropsdef() *) 


The gi__gettrianglepropsdef() function is used to return the default triangle properties. 


gi brush brsh; /*71,STB SOLID, {0, 0, 0} */ 
gi shading shade; /* GRY NONE, all FALSE, {0, 0, 0}, £0, 0, 0} */ 
gi place p1; /* 500, 0 */ 
gi place p2; /* 0, 1000 */ 
gi place p3; /* 1000, 1000 */ 
dp __ bool fixshape; /* FALSE */ 
RETURN VALUE 


If the call is successful 0 is returned, otherwise -1 is returned. The function getsigno() is used to get the 
reason for the failure. 


ERRORS 


gi_get*def() will fail if one or more of the following are true: 


Doc BadParm One of the specified arguments is invalid. 
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gi_relbtnprog 


NAME 


gi__relbtnprog - release button program 
SYNOPSIS 
#include “GraphicsiC.h” 
int 
gi_relbtnprog(btnprog) 
gi__buttonprog *btnprog; 
DESCRIPTION 
The gi_relbtn prog() function is used to release handles obtained by calls to gi_sta rtbtn() or gi_startn btn(). 


The btnprog argument is an opaque variable that points to the handle of the button program to be freed. A 
call to this function will set the respective handle to NULL. 


RETURN VALUE 


If the call is successful 0 is returned, otherwise -1 is returned. The function getsigno() is used to get the 
reason for the failure. 


ERRORS 


gi_relbtnprog() will fail if one or more of the following are true: 
Doc_IllegalHandle The specified handle is illegal. 


Doc TimeOut Inter-process communication has exceeded the maximum allowed time. 
SEE ALSO 


gi_startbtn(),gi__startnbtn() 
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gi__setgframeprops 
NAME 

gi__setgframeprops - set graphics frame properties 
SYNOPSIS 


#include “DocliC.h” 
#include “GraphicsiC.h” 


int 
gi_setgframeprops(aframe, props) 
di_ins aframe; 
gi_gframeprops *props; /* NULL */ 


DESCRIPTION 
The gi_setgframeprops() function is used to set the properties of a graphics frame. 


The aframe argument is an unsigned opaque variable that contains the frame handle returned by an 
earlier calltodi__apaframe(). 


The props argument is a pointer of the type gi__gframeprops. It is a structure that contains specific frame 
properties. gi_gframeprops contains the following members: 


XString name; 
XString desc; 
gi__gridprops gridprops; 


name and desc are the name and description of the graphics frame for which the properties are to be 
set. 


gi__gridprops is a structure that defines the composition of the grid. It contains the following members: 


dp bool act; 

gi gridstyle style; 
gi gridsize size; 
gi_ place offset; 


act, short for activity, indicates the state of the grid. When act is TRUE, the grid is displayed in the 
graphics frame. style and size describe the respective grid type and the interval between grid 


marks. 


style may have one of the following values: 


GRD_DOT /* dot */ 
GRD_ PLUS /* plus */ 
GRD_ TICK /* tick */ 
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size is specified in units of points, where there are 72 points per inch. size may have one of the 


following values: 
GRD 4P I* 4 point */ 
GRD 8P /* 8 point */ 
GRD 12P /* 12 point */ 
GRD 16P /* 16 point */ 
GRD _32P /* 32 point */ 


offset describes the shift values of the upper left grid point relative to the upper left corner of the 
graphics frame. offset is of the type gi place. It is a structure whose two members are integers 
that define the x and y grid locations. Setting both members to 0 indicates that no offset is desired. 
offset is specified in units of points, where 72 points are the equivalent of one inch. 


RETURN VALUE 


If the call is successful 0 is returned, otherwise -1 is returned. The function getsigno() is used to get the 
reason for the failure. 


ERRORS 


gi_setgframeprops() will fail if one or more of the following are true: 
Doc DocumentFull No more room in the document. 
Doc ReadonlyDoc Document opened in ReadOnly mode. 


Doc OutOfDiskSpace Not enough disk space for the operation. 


Doc OutOfVM Not enough virtual memory for the operation. 

Doc _BadParm One of the arguments specified is invalid. 

Doc _IllegalHandile The specified handle is illegal. 

Doc TimeOut Inter-process communication has exceeded the maximum allowed time. 
SEE ALSO 


di_apaframe() 
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gi__startbtn, gi__finishbtn 
NAME 

gi__startbtn, gi__ finishbtn - create and complete an anchored CUSP button frame 
SYNOPSIS 

#include “DociC.h” 

#include "DociCProps.h” 

#include “GraphicsiC.h” 

#include “XString.h” 

int 

gi_startbtn(doc, name, gridprops, wprog, ret) 

di docdoc; 


XString name; /* NULL */ 
gi_gridprops *gridprops; /* NULL */ 
dp __bool wprog; /* FALSE */ 
ret__startbtn *ret; /* Returned */ 
int 
gi_finishbtn(h, ret) 
gi_handleh; 
di_ins *ret; /* Returned */ 
DESCRIPTION 


The gi__startbtn() function is used to begin the creation of an anchored CUSP button. 


The doc argument is of the type di doc, an enumerated variable that contains the document handle 
returned by an earlier call to di_ start() ordi__startap(). 


The name argument is an XString variable that contains either a valid button name or NULL. If name is 
set toNULL, gi__startnbtn() will generate a new unique name for the button, such as Button1, Button2, etc. 


The gridprops argument is a pointer of the type gi_gridprops. It is a structure whose members define the 
style, size, and offset of the grid to be used in the new anchored button. Refer gi_setgframeprops() for a 
description of gi__gridprops. 


The wprog argument is a Boolean value that determines whether the returned gi buttonprog will be 
valid or NULL. Pass FALSE as the value of this argument if you do not intend to use gi ap*tobtnprog() 
functions to append data to the button during the current programming session. Pass TRUE as the value of 
this argument to get a non-NULL program for this button. Complete the implementation of the resulting 
button, gi buttonprog, by calling the various gi ap*tobtnprog() functions. If wprog is set to TRUE, 
gi relbtnprog() must be called to release gi buttonprog after all the desired data has been appended and 
before calling gi finishbtn(). gi finishbtn{() finishes all the non-program aspects of button creation and 
returns an instance to pass as the cont parameter of di__apafra me(). 


The ret argument is a pointer of the type ret startbtn. It is a structure in which will be placed the return 
information. ret__startbtn contains the following members: 


gi_handleh; 
gi__buttonprog prog; 
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h is the graphic handle of a CUSP button. 


prog is a pointer of the type gi_buttonprog. It is an enumerated variable that contains the button 
program data and is supplied as an argument to gi__ad*btn() functions. 


The gi_ finishbtn() function is used to terminate the creation of an anchored button. This function is called 
after all the desired data has been added to the anchored button. 


The hargument to gi finishbtn() is of the type gi handle. It is an enumerated variable that contains the 
anchored button handle returned by an earlier call to gi_startbtn(). 


ret is a pointer of the type di__ins, an enumerated variable that is usually passed as an argument to 
gi_apaframe() only. 


RETURN VALUE 


If the call is successful 0 is returned, otherwise -1 is returned. The function getsigno() is used to get the 
reason for the failure. 


ERRORS 
gi_sta rtbtn() will fail if one or more of the following are true: 


Doc DocumentFull No more room in the document. 

Doc ReadonlyDoc Document opened in ReadOnly mode. 

Doc OutOfDiskSpace Not enough disk space for the operation. 

Doc OutOfVM Not enough virtual memory for the operation. 
Doc BadParm One of the arguments specified is invalid. 

Doc _IllegalHandle The specified handle is illegal. 


Doc TimeOut Inter-process communication has exceeded the maximum allowed time. 


gi_finishbtn() will fail if one or more of the following are true: 


Doc BadParm One of the specified arguments is invalid. 

Doc _illegalHandle The specified handle is illegal. 

Doc TimeOut Inter-process communication has exceeded the maximum allowed time. 
SEE ALSO 


gi__relbtnprog(), gi__finishbtn(), di_apaframe(), gi__setgframeprops() 
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gi__startcluster 


NAME 


gi__startcluster - start cluster 
SYNOPSIS 


#include “GraphicsiC.h” 


int 
gi_startcluster(h, box, ret) 
gi_handleh; 
gi box *box; /* NULL */ 
gi_handle *ret; /* Returned */ 
DESCRIPTION 


The gi_ sta rtcluster() function is used to create a set of graphic objects. Graphic objects may then be placed 
at the location specified in the box argument by passing the handle returned by this function, gi__handle, 
to the appropriate gi _ad*() functions. 


The h argument is the graphics handle returned by an earlier call to gi__startgr(), gi_startgframe(), 
startgframe(), or gi__startbtn(). 


The box argument is a pointer of the type gi__box. It’s two members, place and dims specify the location of 
the container in which is to be placed graphic objects relative to the anchored frame, as well as the size of 
the container. 


gi_place place; 
gi_dims dims; 


gi__ place contains two integer variables x and y. These two variables indicate the grid location of the 
box origin. gi dims contains two integer variables w and h. These two variables indicate the width 
and height of the box with respect to the box origin. Both place and dims are specified in units of 
micas. 


A {0, 0} grid location indicates the upper left corner of a frame. Increasing the value of x causes the 
placement location to shift towards the right. Increasing the value of y causes the placement location 
to shift downwards. It is illegal to specify negative w and h values, therefore an object’s dims.place 
must always correspond to the upper left corner of a box. It is legal to specify negative x and y values. 


box.dims defines the area in which may be placed graphic objects. Increasing the value of w causes the 
frame to grow towards the right. Increasing the value of h causes the frame to grow in a downward 
direction. If an attempt is made to fit a graphic object within a frame that is too small to accommodate 
the graphic object, via calls to gi ad*() functions, only that portion of the object which lies inside the 
frame will be displayed. Those portions of the object which lie outside the frame still exist but are not 
displayed. 


For example, to define the location and area to be occupied by a cluster of graphic objects, box.dims 
and box.place would have the following effect: 
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The cluster will be placed in the resulting area defined by w and h, relative to the location specified by x 
and y. Once the cluster has been defined, graphic objects may be placed within it. 


Once all the desired graphic objects have been added to the cluster, call gi__finishcluster(). 
RETURN VALUE 


If the call is successful 0 is returned, otherwise -1 is returned. The function getsigno() is used to get the 
reason for the failure. 


ERRORS 


gi_startcluster() will fail if one or more of the following are true: 
Doc DocumentFull No more room in the document. 
Doc ReadonlyDoc Document opened in ReadOnly mode. 
Doc OutOfDiskSpace Not enough disk space for the operation. 


Doc OutOfVM Not enough virtual memory for the operation. 

Doc BadParm One of the arguments specified is invalid. 

Doc_IllegalHandie The specified handle is illegal. 

Doc TimeOut Inter-process communication has exceeded the maximum allowed time. 
SEE ALSO 


gi_finishcluster() 
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gi__startgframe 


NAME 


gi_startgframe - start graphics frame 
SYNOPSIS 
#include “DociC.h” 


#include “DociCProps.h” 
#include “GraphicsiC.h” 


int 
gi startgframe(h, box, frprops, gfprops, wtcap, wbcap, wicap, wrcap, ret) 
~ gi handle h; 
gi box *box; /* NULL */ 
gi frameprops *frprops; /* NULL */ 
gi gframeprops *gfprops; /* NULL */ 
dp bool wtcap; /* FALSE */ 
dp bool whcap; /* FALSE */ 
dp bool wicap; /* FALSE */ 
dp bool wrcap; /* FALSE */ 
ret__startgframe *ret; /* Returned */ 
DESCRIPTION 


The gi__startgframe() function is used to nest a graphics frame within a graphics container. The resulting 
frame will have a set of user-defined properties. The handle returned by this function may then be passed 
as an argument to other gi_ad*() functions. 


The h argument is the graphics container handle representing the container into which the nested 
graphics frame is to be placed. This handle may come from several places, most notably gi__startgr(), 
gi_startgframe(), gi_ sta rtbtn(), gi__startnbtn(), or gi_startcluster(). 


The box argument is a pointer of the type gi_box. Refer togi__startcluster() for a description of gi__box. 


The frprops argument is a pointer of the type gi__frameprops. It is a structure that defines the common 
properties of the graphics frame. gi_frameprops contains the following members: 


gi brush brsh; 

dp bool fixshape; 
unsigned mgns[4]; 

di caption capcont[4]; 
dp color bgcol; 

dp __bool tranpare; 


brsh is a structure that defines the visual qualities of the lines comprising the edges of the frame. It 
contains the following variables: 


unsigned wth; 


gi_stlbrush stylebrush; 
dp__color brushcolor; 
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wth is the width of lines, specified in units of micas. The standard brush widths may have one of 
the following value: . 


GSLW1 /* 1 width for Graphics Single Line */ 
GSLW2 /* 2 width for Graphics Single Line */ 
GSLW3 /* 3 width for Graphics Single Line */ 
GSLW4 /* 4 width for Graphics Single Line */ 
GSLW5 /* 5 width for Graphics Single Line */ 
GSLW6 /* 6 width for Graphics Single Line */ 


Each value corresponds to 35, 71, 106, 141, 176, and 212 micas, respectively. Non-standard 
brush widths will result in an error. 


stylebrush defines how the lines are to be drawn, such as solid or dashed. It may have one of the 
following values: 


STB INVISIBLE /* invisible */ 
STB. SOLID /* solid */ 
STB DASHED /* dashed */ 
STB DOTTED /* dotted */ 
STB DOUBLE /* double */ 
STB BROKEN /* broken */ 


The wth of STB DOUBLE borders is 3 times the usual width because it consists of two lines 
separated by a gap equal to the width of the line. In this case, the brush widths may have one of the 
following values: 


GDLW1 /* 1 width for Graphics Double Line */ 
GDL W2 /* 2 width for Graphics Double Line */ 
GDL W3 /* 3 width for Graphics Double Line */ 
GDL W4 /* 4width for Graphics Double Line */ 
GDLW5 /* 5 width for Graphics Double Line */ 
GDL W6 /* 6 width for Graphics Double Line */ 


Each value corresponds to 106, 212, 318, 423, 529, and 635 micas, respectively. The following 
are examples of brush styles: 


ae 


Lace 


INVISIBLE SOLID DASHED DOTTED DOUBLE BROKEN 





brushcolor specifies the color to be used to display the lines that make up the edges of the graphics 
frame. The value of color may be any color that isa member of dp__color. 


fixshape is a Boolean value that, when set to TRUE, indicates that the aspect ratio of a frame will 
remain intact when the user grows or shrinks the box that contains it. A value of FALSE indicates that 
the aspect ratio of the graphic object will change in proportion to the changes made to the box that 
contains it. 
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mgns is an array used to define the margins outside the frame. It requires four values. The values set 
the top, bottom, left, and right margins, respectively. 


capcont is an array used to specify the captions associated with the frame. Its four elements are 
opaque caption handles. The capcont parameter is only meaningful during enumeration and when 
passing the caption handles as arguments to suitable gi ad*() functions, and not when calling 
gi_start*(), since the contents of each caption is added after the frame is created. 


bgcol is a structure comprised of integers that define the background color of the frame. These 
integers are returned from a previous call to a color translation function, such as dp_colfrom name(). 


tranpare is a Boolean value that specifies if the background color of the frame is to be white or 
transparent when the value of bgcol is {0,0,0} (i.e., white). A value of TRUE indicates that the 
background is to be transparent when the color is {0,0,0}. A value of FALSE indicates that the 
background is to be a solid white color. 


gfprops is a pointer of the type gi gframeprops. It is a structure whose members are used to set specific 
frame properties. Refer to the description of gi_setgframeprops() for more information. 


w*cap arguments are Boolean values that specify whether or not the frame is to have captions. If a value 
of TRUE is specified for a w*cap argument. the respective *cap return value will be non-NULL. These 
caption arguments are used to set the top, bottom, left, and right captions, respectively. DoclC functions 
may then be used to add text to each caption. Note that the caption must eventually be freed by a call to 
di relcap(). 


gi_startgframe() sets ret as the return information. ret__startgframe contains the following members: 


gi handle gfh; 


di__caption tcap; 
di_caption bcap; 
di_caption Icap; 


di_caption rcap; 


gfh is the handle to the newly created graphics frame. tcap, bcap, lcap and rcap are the frame captions for 
top, bottom, left and right, respectively. 


Once the desired graphic objects have been added to the frame, gi__finishgframe() must be called to release 
the handle and resources allocated by the system. 


RETURN VALUE 


If the call is successful 0 is returned, otherwise -1 is returned. The function getsigno() is used to get the 
reason for the failure. 





DOCUMENT INTERFACES TOOLKIT SYSTEM REFERENCE Oo — | Bagg 


GRAPHICS IC LIBRARY 


ERRORS 


gi_startgframe() will fail if one or more of the following are true: 
Doc DocumentFull No more room in the document. 
Doc ReadonlyDoc Document opened in ReadOnly mode. 
Doc OutOfDiskSpace Not enough disk space for the operation. 


Doc OutOfVM Not enough virtual memory for the operation. 

Doc _BadParm One of the arguments specified is invalid. 

Doc IllegalHandle The specified handle is illegal. 

Doc_ TimeOut Inter-process communication has exceeded the maximum allowed time. 
SEE ALSO 


di__relcap(),dp__colfromname(), gi__finishgframe(), gi__setgframeprops() 
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gi__startgr 


NAME 


gi__startgr - start to create an anchored frame 
SYNOPSIS 


#include “DociC.h” 
#include “GraphicsiC.h” 
int 

gi_sta rtgr(doc, ret) 


di_docdoc; 
gi_handle *ret; /* Returned */ 


DESCRIPTION 


The gi startgr() function is used to create a graphics frame in a document so that graphic objects may be 
placed within the resulting frame. This function returns a graphics handle, gi handle, which is an opaque 
variable that contains a graphics container. A graphics container is simply an object that may contain 
graphic objects. A graphics container may be a nested graphics frame, a CUSP button within a graphics 
frame, or a similar construct, such as a chart. 


The doc argument is the document file handle that was returned by an earlier call to either di__start() or 
di startap(). 


Once all the desired objects have been added to a frame, call gi__finishgr() to free the handle and the 
resources allocated to that graphics frame. 


RETURN VALUE 


If the call is successful 0 is returned, otherwise -1 is returned. The function getsigno() is used to get the 
reason for the failure. 


ERRORS 


gi_startgr() will fail if one or more of the following are true: 
Doc DocumentFull No more room in the document. 
Doc ReadonlyDoc Document opened in ReadOnly mode. 


Doc OutOfDiskSpace Not enough disk space for the operation. 


Doc OutOfVM Not enough virtual memory for the operation. 

Doc _BadParm One of the arguments specified is invalid. 

Doc _IllegalHandle The specified handle is illegal. 

Doc TimeOut Inter-process communication has exceeded the maximum allowed time. 
SEE ALSO 


di__startap(), gi__startgframe(), gi__startnbtn() 
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gi__startnbtn 


NAME 


gi__startnbtn - start nested button 
SYNOPSIS 


#include “DociC.h” 
#include “DociCProps.h” 
#include “GraphicsiC.h” 
#include “XString.h” 


int 
gi startnbtn(h, box, name, gridprops, frprops, wprog, wtcap, wicap, wrcap, ret) 
~ gi handle h; | 
gi box *box; 
XString name; 


gi gridprops *gridprops; 

gi frameprops *frprops; 

dp bool wprog; /* FALSE */ 
dp bool wtcap; /* FALSE */ 
dp bool wbcap; /* FALSE */ 
dp bool wicap; /* FALSE */ 
dp bool wrcap; /* FALSE */ 
ret__ startnbtn *ret; /* Returned */ 

DESCRIPTION 


The gi__startnbtn() function is used to create a CUSP button in a frame. The resulting button may then 
have CUSP code placed inside it via the prog argument to ret__startnbtn. 


The h argument is the graphics container handle returned by an earlier call to gi__startgframe(), 
gi_cluster(), gi__startnbtn(), or gi__startbtn(). 


The box argument is a pointer of the type gi_box. Refer to gi__adffield() for a description of gi box. 


The name argument is the default name of the button. If this parameter is left NULL, gi_startnbtn() will 
generate a new unique name for the button, such as Button1, Button2, etc. 


gridprops is a pointer of type gi_gridprops. It is a structure whose members determine the composition of 
the grid. Refer to the description of gi__setgframeprops() for more information. 


frprops is a pointer of type gi frameprops. It is a structure whose members determine the common 
properties of the graphics frame. Refer to the description of gi_startgframe() for more information. 


wprog is a Boolean value that, when set to TRUE, indicates that the CUSP button is to have CUSP 
program code added. 


w*cap arguments are Boolean values that specify whether or not the CUSP button is to have captions. Ifa 
value of TRUE is specified for a w*cap argument. the respective w*cap return value will be non-NULL. 
DoclIC functions may then be used to add text to each caption. Note the caption must eventually be freed by 
a call to di__relcap(). 


If the w* cap arguments are set to TRUE, and a call to this function returns a valid button program handle, 
the returned handle must later be freed by a call to gi__relbtnprog(). GraphicsIC provides several functions 
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that the user can call to add data to the CUSP program; refer to gi_ap*btnprog(), for information 
regarding these functions. 


ret is a pointer to ret_ startnbtn. It is a structure for the return information. It contains the following 
members: 


gi handle bfh; 

gi buttonprog prog; 
di caption tcap; 

di caption bcap; 

di caption Icap; 
di__caption rcap; 


The bfh argument is the handle to the newly created button. prog is a handle to the CUSP program 
code to be used by gi__ap*btnprog functions. 


tcap, bcap, Icap, and rcap are as described above. 


Once the desired graphics objects have been added to the frame, gi__finishnbtn() must be called to 
release the handle and resources allocated by the system. 


RETURN VALUE 


If the call is successful 0 is returned, otherwise -1 is returned. The function getsigno() is used to get the 
reason for the failure. 


ERRORS 


gi_ sta rtnbtn() will fail if one or more of the following are true: 
Doc Docu mentFull No more room in the document. 
Doc ReadonlyDoc Document opened in ReadOnly mode. 


Doc OutOfDiskSpace Not enough disk space for the operation. 


Doc OutOfVM Not enough virtual memory for the operation. 

Doc BadParm One of the arguments specified is invalid. 

Doc_IllegalHandle = The specified handle is illegal. 

Doc TimeOut Inter-process communication has exceeded the maximum allowed time. 
SEE ALSO 


gi_startgframe(),gi_relbtnprog(),gi__ap*tobtnprog(), di__relcap(), gi__finishbtn(), gi__adffield(), 
gi__setgframeprops(). 
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ti__intro 


NAME 


ti__intro - introductory explanation of table functions 
DESCRIPTION 


TablelC functions are used to read the contents of a table, create a new table, or add information to an 
existing table. 


A table is defined by three types of properties: table properties, column properties, and row properties. 
Table properties include the name of the table, a description of the table headers, and the number of 
columns and rows in the table; column properties include the division of columns and the alignment of text 
within columns; and row properties include information about how the text is to be aligned within a given 
row. The actual data of a table is included with the row information. 


Table Building 


The first step in generating a new table is usually acalltoti starttable(). A call to this function will cause 
a table handle to be returned. The handle is a static variable that contains, in addition to table-related 
data, a pointer to the contents of the table. (Refer to ti *props for a diagram that depicts the structure ofa 
table.) It is this handle that is passed to other ti *() functions as the means of identifying the table within 
the document and its associated properties. At this point, the row properties have default values and the 
contents of the table is nil. The contents and properties of each row are later added to the table via calls to 
other ti__*() functions. 


To add data to a table, pass the table handle returned byti starttable()asanargumenttoti appendrow(). 
ti appendrow() will add a row to the end of the table and insert the specified contents into that row. 
ti appendrow() is to be called repeatedly until all the rows and their contents have been appended to the 
table. When the table is complete, call ti finishtable() to finalize the structure of the table. Once finalized, 
ti finishtable() returns an instance of the table, di ins. This instance is comprised of only the rows and 
contents of the table frame; the remaining table properties, such as captions and border style, are added 
later via calls to related DoclC or GraphicsIC functions, such as di__apaframe() or gi__adtable(). 


The preceding paragraphs describe how to create a new table and then add data to it. To add information 
to anexisting table, callti startextable()ratherthan ti starttable().ti startextable() is used to initialize 
a table in a document for editing. ti startextable() is called with an instance of the table, di ins, as an 
argument and returns a handle to that table. The table instance passed to ti startextable() may be 
obtained by a call to di enumerate(). When di enumerate() is used to obtain the instance, the original 
document handle supplied as an argument to di__enu merate() must have originally come from di__startap(). 


The table handle returned by ti_ sta rtextable() may then be passed as an argument toti__appendrow() and 
ti__finishtable(). 
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Table Reading 


The contents of a table are typically read by calling the ti enumtable() function. This function requires an 
instance of a table, di ins, and a set of three call-back procedures as arguments. The three call-back 
procedures are ti__tableproc(), ti_ columnproc(), and ti__rowproc(). 


The ti __enumtable() function calls ti __tableproc() andti columnproc() once while processing a table; these 
procedures extract the table and column properties. Since the contents of a table are stored with the rows, 
ti_ enumta ble() calls ti_r rowproc() once for each row encountered in the table. 


Properties 


4-2 


Table Properties 


ti__tableprops describes the properties of a table and its headers. ti__tableprops contains the following 
members: 


XString name; 
unsigned nrows; 

dp bool fxrows; 
unsigned ncols; 

dp bool fxcols; 

dp bool fillinbyrow; 
dp bool reptop; 

dp bool repbottom; 
dp bool deferon; 

dp bool vsblihd; 

dp bool rephd; 
ti__hdalignment halign; 
ti _valignment valign; 
unsigned thdmgn; 
unsigned bhdmgn; 

ti line bdrline; 

ti line dvrline; 
ti__sortkeys *sortkeys; 


name is an XString that specifies the name of the table. 


nrows is an integer that specifies the number of rows in the table. This value is valid only upon 
reading by ti__enumtable(). fxrows is a Boolean value that specifies whether or not the user may 
change the number of rows in the table. 


ncols is an integer that specifies the number of columns in the table. This value is valid only upon 
reading by ti__ enumtable(). fxcols is a Boolean value that specifies whether or not the user may 
change the number of columns in the table. 


fillinbyrow is a Boolean value that determines what happens when the user presses the NEXT key. 
If fillinbyrow is TRUE, pressing the NeExT key advances through the table one column at a time, and 
the table is expanded by rows. In this case, the number of columns is fixed and the number of rows 
can be either fixed or varying. If fillinbyrow is FALSE, then pressing the NExT key advances 
through the table one row at a time, and the table is expanded by columns. In this case, the 
number of rows is fixed and the number of columns can be either fixed or varying. 


vsblhd is a Boolean value that indicates whether or not there should be a visible header at the top 


of the table; rephd, reptop, repbottom are Boolean values that indicate whether or not to repeat 
the header, table top, or table bottom on every page when the table spans multiple pages. 
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deferon is a Boolean value that indicates whether the pagination operation will defer the table 
frame to the next page if it cannot fit on the current page. If deferon is FALSE, that portion of the 
table that will fit on the current page will be placed on that page, and the remainder will placed on 
successive pages. 


halign and valignm are values of the type ti_ hdalignment and ti__valignment, respectively. They 
specify the alignment of text within a header. 


ti__hdalignment may have one of the following values: 


HD LEFT /* left */ 
HD CENTER /* center */ 
HD RIGHT /* right */ 


ti valignment may have one of the following values: 


VA_FTOP /* flush stop */ 
VA_ CENTER /* centered */ 
VA_FBOTTOM /* flush bottom */ 


thdmgn and bhdmgn are integers that specify the amount of white space that should appear 
between above and below each header element. Values are specified in units of micas. 


bdrline describes the table border (not the frame border), and dvrline describes the line between 
the header row and the rest of the table. A line may have a width anywhere from one pixel to six 
pixels. Both bdrline and dvrline are of the type ti__line. 


ti line is a structure whose members describe the properties of the line. It contains the 
following members: 


ti__linestyle style; 
ti__linewidth width; 


ti__linestyle is an enumerated type that may have one of the following values: 


LS NONE /* none */ 
LS SOLID /* solid */ 
LS DASHED /* dashed */ 
LS DOTTED /* dotted */ 
LS DOUBLE /* double */ 
LS BROKEN /* broken */ 


ti__linewidth may have one of the following values: 


LW W1 /* width of 1 pixel */ 
LW Ww2 /* width of 2 pixel */ 
LW W3 - /* width of 3 pixel */ 
LW W4 /* width of 4 pixel */ 
LW WS5 /* width of 5 pixel */ 
LW W6 /* width of 6 pixel */ 


The argument sortkeys is a pointer of the type ti__ sortkeys. It determines whether columns are 
sorted in ascending or descending order. It contains the following members: 


unsigned length; 
ti__sortkey *keys; 
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ti sortkeys is comprised of an integer, length, and an optional array of ti sortkey, where there 
may be one ti sortkey specified for each table or column. A column must be divided-repeating in 
order to have sort keys. The integer specifies the number of columns comprising the table. 
ti__sortkey contains the following members: 


XString name; 
dp__bool ascend; 


ti sortkey consists of a string that specifies the column’s name and a Boolean value that indicates 
whether to sort in ascending or descending order. A value of TRUE will result in an ascending sort 
order. 


Column Properties 


ti__colinfoseq describes the properties of all the columns in a table. ti__colinfoseq is a structure 
comprised of the following members: 


unsigned length; 
ti__colinforec *seq; 


length is an integer that specifies the number of columns in the table. 


seq is a pointer of the type ti colinforec. Its members describe the properties of each column. The 
most complicated field in ti colinforec is hdentry; all of the other fields correspond directly to the 
fields on the property sheet. The main column header properties are described below. The 
remaining column properties are described in the section titled Other Column Properties. 


ti__colinforec contains the following members: 


ti hdentry hdentry; 
XString name; 

XString desc; 

dp bool divid; 
unsigned subcols; 

dp bool repeat; 

ti colinfo subcolinfo; 

ti halignment alignment; 
unsigned taboffset; 
unsigned width; 
unsigned Imgn; 
unsigned rmgn; 

dp_ fidchoice type; 

dp bool req; 

dp lang lang; 

XString format; 

dp bool stpskp; 
XString range; 

unsigned length; 
XString skptext; 

dp skpchoice skpchoice; 
XString fillin; 

dp fontruns *fillinruns; 
ti Tine line; 
ti__sortkeys *sortkeys; 
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Column Header Properties 


ti__hdentry is a structure whose members describe the textual content of each column header. The text 
in each column header may contain an unlimited number of font and paragraph properties. ti__hdentry 
contains the following members: 


ti hdinfo subhds; 
ti line line; 

dp bool hint; 
ti__ entry cont; 


subhds is a value of the type ti hdinfo. It is used to describe the headers of each subcolumn. This 
argument is applicable only if the column in question has been divided. subhds points to 
ti hdinfoseq, a structure whose members define the number of columns in the table, including the 
ti hdentry variable of each subcolumn. Each subcolumn may in turn be subdivided, in which case 
that subcolumn’s ti__hdentry.subhds field will point to another array. 


ti__hdinfoseq contains the following members: 


unsigned length; 
ti__hdentry *seq; 


Refer to the figure below for a graphic description of the flow of ti_ *() functions and the 
composition of headers and columns. 
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line is a value of the type ti line. Its members describe the properties of the line that divides the 


header from subheaders. line contains the following members: 


ti__linestyle style; 
ti__linewidth width; 


ti__linestyle is an enumerated type that may have one of the following values: 


LS NONE 
LS SOLID 

LS DASHED 
LS DOTTED 
LS DOUBLE 
LS BROKEN 


ti__ linewidth is an enumerated type that may have one of the following values: 


LW W1 
LW Ww2 
LW W3 
LW W4 
LW WS5 
LW W6 


/* none */ 
/* solid */ 
/* dashed */ 
/* dotted */ 
/* double */ 
/* broken */ 


/* width of 1 pixel */ 


/* width of 2 pixel 
/* width of 3 pixel 
/* width of 4 pixel 
/* width of 5 pixel 
/* width of 6 pixel 


line is visible only when the column is subdivided. 


or 
a 
*] 
*/ 
*/ 


hint is a Boolean value that indicates that the header is to contain only one line of text. Setting 
this value to TRUE will result in faster processing because it simplifies the calculation of header 
size. If hint is set to TRUE and then one or more lines of text are appended to the header text, the 
resulting header entry will display only the first line of text, though more text is present. If this 
situation occurs, it may be corrected by editing the text in the header, which will cause the 
Document Editor to recompute the header’s height. 


cont is a value of the type ti__entry. It is a union whose members describe the textual contents of a 
header and the access permissions to those contents. It contains the following members: 


enum { 
READ = 0, 
WRITE = 1 
} mode; 
union { 
di text text; 
wcont weont; 


}u; 


/* NULL */ 


wcont contains the following members: 


ti fillintxtproc *proc; 


—e 


void *cdat; 


/* NULL */ 
/* NULL */ 


When enumerating a table, all the header and row entry permissions will be set to READ. 
di text may be called to enumerate the text. Upon completion, there is no need to call 


di reltext(). 
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When creating a table, set all header and row entries to WRITE. ti fillintxtproc call-back 
procedures may be invoked to fill the table with text. The value of cdat will be passed to 
ti fillintxtproc. 
Other Column Properties 
name and desc are the name and description of the column as it would appear in the property sheet. 
divid specifies whether the columns may be divided. subcols is the number of subcolumns; repeat 
indicates that subcolumns may have subrows, and subcolinfo is a recursive description of each 
subcolumn. subcols, repeat, and subcolinfo are ignored if divid is FALSE. 
alignment describes the alignment of text within a column. 
taboffset specifies where decimal tabs are to be set, relative to the margin. taboffset only applies if 
alignment is THA DECIMAL. taboffset is specified in units of micas. Note that this is different than 


dp__taboffset, which is measured in units of points. 


width is the width of a column; Imgn and rmgn are the margins of a column. If the column is divided, 
these parameters are ignored. These values are also specified in units of micas. 


type indicates the type of contents to be placed in the column. 


req indicates that data must be entered into a field before the user is permitted to proceed to another 
field in the table. 


lang determines the format of the date and amount fields. It is used when items are added to the 
paragraph. 


format allows the user to define a format to which the data in a column must conform. 


stpskp controls the manner in which the skipping action of the SKIP button works. When set to TRUE, 
the skipping action will stop at the next entry in a column. 


range defines a specific range of acceptable entries for the column. Once defined, an entry that does 
not match the criteria specified in range is not accepted. 


length specifies the maximum number of characters to be entered into the column. 


skptext and skpchoice define the conditions under which an entry may be skipped when the user 
presses NEXT. 


fillin describes the fill-in rule for the column. 
fillinruns describes the font properties of fillin. 
line describes the properties of the vertical line to the right of the column. 
sortkeys describes the sort keys for the column. 
Row Content 


ti__rowcont is a pointer to ti__rowcontseq. ti__rowcontseq is a pointer to a structure that describes the 
properties and contents of a row. It contains the following members: 
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unsigned tmgn; 
unsigned bmgn; 

ti line line; 

ti valignment valign; 
unsigned length; 
ti__rowent *rowdat; 


tmgn and bmgn are the row margins. That is, the margin above the top row and below the bottom 
row. line is the properties of the line separating the rows. valign specifies the alignment of text 
within a row. rowdat describes the contents of the row. 
ti__ rowent describes the textual content of a given row entry and contains the following members: 
ti__subrows *subrows; 
dp bool hint; 
ti__entry cont; 
ti__subrows describes the properties and contents of a subrow. If subrows is non-NULL, then the 
restoftheti rowent record is unused, since the textual information will be in each individual 


subrow record. ti subrows contains the following members: 


unsigned length; 
ti rowcont rows; 


Note that subrows may exist only if the parent column is divided. 


The remaining fields are as described in the header file. 
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ti__ appendrow 


NAME 


ti__appendrow - append row 
SYNOPSIS 
#include "TablelC.h” 


int 
ti appendrow(h, rc) 
~ ti handleh; 
ti__rowcont rc: 


DESCRIPTION 
The ti__appendrow() function is used to add a row to a table. 


his the value of ti handle, an opaque variable that contains the table handle returned by an earlier call to 
either ti_ starttable() or ti_ startextable(). 


rcis the value of the type ti_ rowcont. It is a structure whose members specify the margins and alignment 
of the row, as well as its contents. It contains the following members: 


unsigned tmgn; 
unsigned bmgn; 

ti line line; 

ti valignment valign; 
unsigned length; 

ti__ rowent *rowdat; 


RETURN VALUE 


If the call is successful 0 is returned, otherwise -1 is returned. The function getsigno() is used to get the 
reason for the failure. 


ERRORS 


ti__appendrow() will fail if the following is true: | 
Doc _TableTooTall The specified table is too high to fit in the table frame. 
Doc BadParm One of the specified arguments is invalid. 
Doc_IllegalHandle The specified handle is illegal. 


Doc TimeOut Inter-process communication has exceeded the maximum allowed time. 
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ti__deffont, ti__defpara 


NAME 
ti__deffont, ti__defpara - default font and paragraph properties 


SYNOPSIS 


#include “DociCProps.h” 
#include "TableiC.h” 


int 
ti__deffont(ret) 
dp_fontprops *ret; /* Returned */ 
int 
ti_ defpara(ret) 
dp__paraprops *ret; /* Returned */ 
DESCRIPTION 


Theti deffont() and ti__defpa ra() functions are used to assign default font and paragraph property values 
to the elements of a table. | | 


These functions return dp _fontprops and dp __paraprops, respectively. The property structures that are 
returned contain default font or paragraph property values. The returned structures may be trapped and 
passed as arguments to the various table manipulation functions that require font or paragraph 
properties. 


RETURN VALUE 


If the call is successful 0 is returned, otherwise -1 is returned. The function getsigno() is used to get the 
reason for the failure. 


ERRORS 


ti__def*() will fail if the following is true: 
Doc BadParm One of the specified arguments is invalid. 


Doc TimeOut Inter-process communication has exceeded the maximum allowed time. 
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ti__enumtable 


NAME 


ti__enumtable - read table 


SYN 


OPSIS 


#include “DociC.h” 
#include “TablelC.h” 


int 
ti enumtable(table, procs, cdat) 


CAL 


ti 
ti 


ti 
ti 


ti 
ti 


~ di_ins table; 
ti enumprocs *procs; 
void *cdat; /* NULL */ 


LBACK PROCEDURE 


stop 
~ columnproc(cdat, columns) 
~ void *cdat; 

ti__colinfo columns; 


stop 
~ rowproc(cdat, cont) 
~ void *cdat; 

ti__ rowcont cont; 


stop 

~ tableproc(cdat, props) 

~ void *cdat; 
ti__tableprops *props; 


DESCRIPTION 


T 


T 
T 


he ti__enumtable() function is used to parse the contents of a table. 


he table argument is the value of di ins, an opaque variable that contains an instance of a table handle. 
he procs argument is the value of ti enumprocs, a structure comprised of call-back procedures. Its 


members extract the properties of the table itself, and the properties of the columns and rows comprising 
the table. ti_ enumprocs contains the following members: 


E 
Ww 
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ti__tableproc *table; /* NULL */ 
ti__columnproc *column; /* NULL */ 
ti__rowproc *row; /* NULL */ 


table, column, and row are pointers to the respective procedures. table and the column are called 
once, but, since the data comprising a table is stored with the rows, ti__ enumtable() calls row once for 
each row in the table. 


ach call-back procedure returns a Boolean value. If the return value of ti_ stop is TRUE, the enumeration 
ill stop. 
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RETURN VALUE 


If the call is successful 0 is returned, otherwise -1 is returned. The function getsigno() is used to get the 
reason for the failure. 


ERRORS 


ti__enumtable() will fail if the following is true: 


Doc BadParm One of the specified arguments is invalid. 


Doc_IllegalHandle = The specified handle is illegal. 


Doc_ TimeOut Inter-process communication has exceeded the maximum allowed time. 
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ti__finishtable 


NAME 
ti__finishtable - finish table 


SYNOPSIS 
#include “TablelC.h” 
int 
ti__finishtable(h, ret) 
ti__ handle h; 
ret_ ft *ret; /* Returned */ 


DESCRIPTION 


The ti__finishtable() function is used to close the table currently being edited. This function must be called 
when no more edits are to be performed on the table. 


his the value of ti handle, an opaque variable that contains the table handle returned by an earlier call to 
either ti_ starttable() or ti_ startextable(). 


Once called, this function returns ret_ ft, a structure that may be passed as the cont argument to 
di _apaframe() or as the table argument to gi_adtable(). ret_ ft contains the following members: 


di_ ins table; 
unsigned width; 
unsigned height; 


RETURN VALUE 


If the call is successful 0 is returned, otherwise -1 is returned. The function getsigno() is used to get the 
reason for the failure. 


ERRORS 


ti__finishtable() will fail if the following is true: 
Doc BadParm One of the specified arguments is invalid. 
Doc_IllegalHandle The specified handle is illegal. 


Doc TimeOut Inter-process communication has exceeded the maximum allowed time. 
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ti__get*def 


NAME 
ti__get*def - get default properties 


SYNOPSIS 


#include “TablelC.h” 


int 
ti__getlinedef(line) 

ti__line *line; /* Returned */ 
int 
ti__getsortkeydef(sort) 

ti__sortkey “sort; /* Returned */ 
int 
ti__getcolinforecdef(col) 

ti__colinforec *col; /* Returned */ 
int 
ti__gethdentrydef(hdentry) 

ti__hdentry *hdentry; /* Returned */ 
int 
ti__getrowentdef(rowentry) 

ti_ rowent *rowentry; /* Returned */ 
int 
ti__gettablepropsdef(props) 

ti__tableprops *props; /* Returned */ 

DESCRIPTION 


The ti__getlinedef() function is used to get default line properties . Their values are: 


ti__linestyle style; /* LS SOLID */ 
ti__linewidth width; /* LW W1 a 


The ti__getsortkeydef() function is used to get default sort key properties. Their values are: 


XString name; /* NULL */ 
dp__bool ascend; /* TRUE */ 


The ti__getcolinforecdef() function is used to get default column properties . Their values are: 


ti hdentry hdentry; /* nullti hdentry */ 
XString name; /* NULL *7 

XString desc; /* NULL */ 

dp bool divid; /* FALSE */ 
unsigned subcols; j*0*/ 

dp bool repeat; /* FALSE */ 

ti colinfo subcolinfo; /* NULL */ 


ti_halignmentalignment; = /* VA_CENTER*/ 
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unsigned taboffset; /*Q */ 

unsigned width; /* 2540 */ 

unsigned Imgn; /* 0 */ 

unsigned rmgn; /* 0 */ 

dp _ fidchoice type; /*FLD ANY */ 

dp bool req; /* FALSE */ 

dp lang lang; /* USE (USEnglish) */ 
XString format; /* NULL */ 

dp bool stpskp; /* FALSE */ 

XString range; /* NULL */ 

unsigned length; /* 0 */ 

XString skptext; /* NULL */ 

dp skpchoice skpchoice; /*SKP EMPTY */ 
XString fillin; /* NULL */ 

dp fontruns *fillinruns; /* NULL */ 

ti Tine line; /*LS SOLID, LW W2*/ 
ti__sortkeys *sortkeys; /* NULL */ ~ 


The ti_ gethdentrydef() function is used to get default header entry properties . Their values are: 


ti hdinfo subhds; /* NULL */ 

ti line line; /*LS SOLID,LW W2*/ 
dp bool hint; /* FALSE */ _ 
ti__entry cont; hase | 


The ti__getrowentdef() function is used to get default row entry properties . Their values are: 


ti__subrows *subrows; /* NULL */ 
dp_bool hint; /* FALSE */ 
ti__entry cont; [fo Sy 


The ti__gettablepropsdef() function is used to get default table properties . Their values are: 


XString name; /* NULL */ 
unsigned nrows; /*Q*/ 

dp bool fxrows; /* FALSE */ 
unsigned ncols; /* 0 */ 

dp bool fxcols; /* TRUE */ 
dp bool fillinbyrow; /* TRUE */ 
dp bool reptop; /* TRUE */ 
dp bool repbottom; /* TRUE */ 
dp bool deferon; /* FALSE */ 
dp bool vsblihd; /* TRUE */ 
dp bool rephd; /* TRUE */ 


ti hdalignment halign; 
ti__valignment valign; 
unsigned thdmgn; 
unsigned bhdmgn; 

ti line bdrline; 

ti line dvrline; 
ti__sortkeys *sortkeys; 


/*HD CENTER */ 

/*VA_ CENTER */ 
/*0*/ 

/* 0 */ 

/*LS NONE,LW W1*/ 
/*LS SOLID, LW W4*/ 
/* NULL */ _ 


RETURN VALUE 


If the call is successful 0 is returned, otherwise -1 is returned. The function getsigno() is used to get the 
reason for the failure. 
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ti__gettableprops 


NAME 


ti__gettableprops - get table props from name 
SYNOPSIS 


#include “DociC.h” 
#include “TablelC.h” 
#include ”XString.h” 
int 
ti gettableprops(doc, name, ret) 
~ di docdoc; 
XString name; 
ti__tableprops *ret; /* Returned */ 


DESCRIPTION 
The ti__gettableprops() function is used to extract the properties of a named table. 


The doc argument is the value of di__doc, an opaque variable that contains the handle of the document 
which, in turn, contains the table in question. 


The name argument is a text string that specifies the name of the table from which to extract the table 
properties. 


This function returns a pointer to ti_ tableprops, a structure that contains the properties of the named 
table. All the fields in the structure will accurately reflect the properties of the table except for the name 
field. It will be NULL. See ti__starttable() for a listing of ti__tableprops members. 


RETURN VALUE 


If the call is successful 0 is returned, otherwise -1 is returned. The function getsigno() is used to get the 
reason for the failure. 


ERRORS 


ti__getta bleprops() will fail if the following is true: 
Doc BadParm One of the specified arguments is invalid. 
Doc_IllegalHandle The specified handle is illegal. 


Doc TimeOut Inter-process communication has exceeded the maximum allowed time. 
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ti__maxelm 


NAME 


ti__maxelm - maximum table elements 
SYNOPSIS 
#include “TablelC.h” 
int 
ti__maxelm(ret) 
unsigned *ret; /* Returned */ 


DESCRIPTION 


The ti__maxelm() function is used to estimate the number of table cells that could reside in a document that 
does not contain other structures. The value that is returned may be used to estimate how big a table may 
be created within the document. 


RETURN VALUE 


If the call is successful 0 is returned, otherwise -1 is returned. The function getsigno() is used to get the 
reason for the failure. 


ERRORS 
ti__maxelm() will fail if the following is true: 
Doc BadParm One of the specified arguments is invalid. 
Doc TimeOut Inter-process communication has exceeded the maximum allowed time. 
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ti__startextable 


NAME 


ti__startextable - open an existing table 
SYNOPSIS 


#include “DocliC.h” 
#include “DocliCProps.h” 
#include "TablelC.h” 


int 
ti__startextable(table, hi, rowsource, deleterow, ret) 
di_ ins table; 


ti__hdinfo hi; /* NULL */ 

unsigned rowsource; /* 0 */ 

dp bool deleterow; /* TRUE */ 

ti_handle *ret; /* Returned */ 
DESCRIPTION 


The ti__startextable() function is used to add data to an existing table. Data is added by appending rows 
which contain the data to the existing table. 


The table argument is the value of di__ins, an opaque variable that points to an instance of a table. 


hi is the value of ti__hdinfo, a pointer to the structure ti__hdinfoseq. This structure contains the following 


members: 
unsigned length; /* Number of ti__hdentry */ 
ti__hdentry *seq; /* Array of ti__hdentry */ 


ti_ hdentry is a structure that is specified as an array, with one ti_ hdentry specification per table 
column header. The members of ti hdentry specify the contents and appearance of a column header in 
the table. ti__hdentry contains the following members: 


ti hdinfo subhds; 
ti line line; 

dp bool hint; 
ti__entry cont; 


length is an integer that specifies the number of ti hdentry entries in the array of ti__hdentry. 
If hi is NULL, then the existing column headers are used. 


rowsource is the index of a row in the table. The properties of the specified row will be extracted and 
applied as the default properties to each new row. The range of the index is between 0 and n, inclusive, 
where n is the number of rows. All properties of the new row, except for the horizontal alignment, are 
taken from the row specified in rowsource. The horizontal alignment of each element of the new row is the 
same as that of the first row. 


deleterow is a Boolean value that indicates whether the table contents should be deleted before adding 


new information. When set to TRUE, all the rows and their contents are deleted from the table, except for 
header information. 
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Like ti__sta rttable(), ti__sta rtextable()returnsti handle, an opaque variable that containsa table handle. It 
may then be passed as an argument to ti__a ppendrow() and ti__finishtable(). 


RETURN VALUE 


If the call is successful 0 is returned, otherwise -1 is returned. The function getsigno() is used to get the 
reason for the failure. 


ERRORS 


ti__sta rtextable() will fail if the following is true: 
Doc ReadonlyDoc The document is read-only. 
Doc BadParm One of the specified arguments is invalid. 
Doc_IllegalHandle The specified handle is illegal. 


Doc TimeOut Inter-process communication has exceeded the maximum allowed time. 
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ti__starttable 


NAME 


ti__starttable - create a new table 
SYNOPSIS 


#include “DociC.h” 
#include “TablelC.h” 


int 
ti starttable(doc, props, col, ret) 
~ di docdoc; 
ti tableprops *props; 
ti colinfo col; 
ti__handle *ret; /* Returned */ 


DESCRIPTION 
The ti__sta rttable() function is used to add a new table to a document. 


The doc argument is the value of di__doc, an opaque variable that contains the document handle for the 
document to which the table will be added. 


The props argument is a pointer to ti tableprops, a structure whose members specify the properties of the 
new table. These properties include the name of the table, the number of columns and rows to be assigned, 
the alignment of the table within the frame, and so on. ti__tableprops contains the following members: 


XString name; 
unsigned nrows; 

dp bool fxrows; 
unsigned ncols; 

dp bool fxcols; 

dp bool fillinbyrow; 
dp bool reptop; 

dp bool repbottom; 
dp bool deferon; 

dp bool vsbihd; 

dp bool rephd; 

ti hdalignment halign; 
ti valignment valign; 
unsigned thdmgn; 
unsigned bhdmgn; 

ti line bdrline; 

ti line dvrline; 
ti__sortkeys *sortkeys; 


col is the value of ti__colinfo, a pointer toa structure of the type ti__colinfoseq. ti__colinfoseq is an array of 
ti colinforec, withoneti colinforec per each column ina table. It specifies the properties ofa column, such 
as headers, width, margins, and the text to put in each columns. ti__colinforec contains the following 
members: 


ti hdentry hdentry; 


XString name; 
XString desc; 
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dp bool divid; 
unsigned subcols; 

dp bool repeat; 

ti _colinfo subcolinfo; 
ti halignment alignment; 
unsigned taboffset; 
unsigned width; 
unsigned Imgn; 
unsigned rmgn; 

dp fidchoice type; 

dp bool req; 

dp lang lang; 

XString format; 

dp bool stpskp; 
XString range; 
unsigned length; 
XString skptext; 

dp skpchoice skpchoice; 
XString fillin; 

dp fontruns fillinruns; 
ti Tine line; 
ti__sortkeys *sortkeys; 


This function returns ret, a pointer to ti handle. ti handle is an opaque variable that contains a table 
handle. _ a 


ti starttable() will raise a Doc Docu mentFull error if the table and header row can not fit in the document. 
This error is raised when there is no more room to add an object (e.g., a table) into the specified document. 
The size of a VP document may be as large as disk space allows but the structured portions may not exceed 
255 disk pages. One disk page is comprised of 512 bytes. 

RETURN VALUE 


If the call is successful 0 is returned, otherwise -1 is returned. The function getsigno() is used to get the 
reason for the failure. 


ERRORS 


ti__starttable() will fail if one or more of the following are true: 


Doc _DocumentFull No more room in the document. 

Doc _TableTooWide The specified table is too wide to fit in the document. 

Doc _TableHeaderTooTall The specified headers are too tall. 

Doc BadParm One of the specified arguments is invalid. 

Doc_IllegalHandle The specified handle is illegal. 

Doc_ TimeOut Inter-process communication has exceeded the maximum allowed 


time. 
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dsktp__intro 


NAME 
dsktp__intro - introductory description of Desktop functions 
DESCRIPTION 


Desktop functions are used to manipulate existing document files and folders located on the Desktop or to 
add new files and folders to the Desktop. dsktp *() functions are used to copy or delete existing files, make 
folders, and more. The most important aspect of Desktop functions is that they allow the interaction 
between files on the desktop and the editing functions of other interfaces, such as those in DociC and 
GraphicsIC. 


di start() is called as the first step in the document generation process. Afterwards, the contents of a 
document may be appended using DocIC and GraphicsIC functions. Lastly, di finish() is called to finalize 
the document. di finish() returns a reference, or handle, to the newly created document. This reference 
may be passed in calls to other dsktp *() functions. Typically, this reference is passed as an argument ina 
calltodsktp movedoc(). The result of this function is to take the new file, which currently exists only ina 
buffer, and place it on the Desktop. Once on the Desktop, the new file may be manipulated like any other 
document. 


When manipulating an existing document, dsktp _enumerate() or dsktp__getdocref() is called as the first 
step in the document editing process. The reference that is returned may then be passed as an argument to 
di open() or di startap(). These functions return a handle, di doc, that may be passed to document 
editing functions, such as those contained within in the Document IC Library and the Graphics IC 
Library. The last step in the editing process is to indicate that the document is finished by a call to, either, 
di close() or di finish(). The finished document still resides in a temporary buffer. To move it from the 
buffer onto the Desktop, dsktp__movedoc() must be called. 
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dsktp__checkuser 


NAME 
dsktp__checkuser - verify the VP user identity 


SYNOPSIS 


#include “Desktop.h” 
#include “DociCProps.h” 


int 
dsktp checkuser(user, passwd, ret) 
char *user; 
char * passwd; 
dp_bool *ret; /* Returned */ 


DESCRIPTION 
Thedsktp checkuser() function is used to verify the identity of a user accessing the Desktop. This function 


checks both the user name and password. 


The user argument is a string that indicates the user to be validated. It is specified in the form: 
name:domain:organization. 


The passwd argument is a string that specifies the VP password of the person identified in the user 
argument. 


The ret argument is where the results of dsktp__checkuser() are placed. ret will have a Boolean value. The 
value will be TRUE only when both the name and password supplied match the current VP logon user 
name and password. 


RETURN VALUE 


0 is returned if the call is successful, otherwise -1 is returned. The function getsigno() is used to get the 
reason for the failure. 


ERRORS 


dsktp _checkuser() will fail if one or more of the following are true: 


Doc BadParm One of the specified arguments is invalid. 
Doc_ TimeOut Inter-process communication has exceeded the maximum allowed time. 
SEE ALSO 
dsktp__getaccess() 
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dsktp__copydoc 


NAME 
dsktp__copydoc - duplicate a document 


SYNOPSIS 
#include “Desktop.h” 


int 
dsktp copydoc(ref, new) 
dsktp_docref ref; 
dsktp__docref new; /* Returned */ 


DESCRIPTION 


The dsktp _copydoc() function is used to copy a document and return a handle to the duplicate document. 


The ref argument is an opaque variable of the type dsktp__docref. It is a reference to the document that is 
to be copied. ref was returned by anearliercalltodsktp getdocref() ordsktp _enumerate(). 


The new argument is also an opaque variable of the type dsktp docref. This argument defines the 
structure of the return information into which will be placed the handle information for the duplicate 
document. 


Note that this function does not generate an icon for the duplicate document, only a handle to it. If an icon 
is desired for the duplicate document, use the dsktp movedoc() function. At which time, a unique name 
may be assigned to the duplicate document. 


RETURN VALUE 


0 is returned if the call is successful, otherwise -1 is returned. The function getsigno() is used to get the 
reason for the failure. 


ERRORS 


dsktp _copydoc() will fail if one or more of the following are true: 


Doc BadParm One of the specified arguments is invalid. 

Doc TimeOut Inter-process communication has exceeded the maximum allowed time. 

DT _FileChanged The file has been modified during program execution such that it cannot be 
used. 


DT_FileDamaged The file has been internally damaged. 

DT _FilelnUse The specified file is in use by another application. 
DT__FileNotFound The file was not found in the expected context. 

DT _ Illegal One of the arguments to the function call is invalid. 


DT FileNotUnique The directory already contains a file of the same name (if the 
UniquelyNamedContents of Folder Properties is set to TRUE) or the same 
name and version (if the UniquelyNamedContents of Folder Properties is set 
to FALSE). 


BT _LoopinHiera rchy The directory is the same as, or a descendant of, the file being moved or copied. 
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DT MediumFull 
DT NoAccessRight 


SEE ALSO 


dsktp _movedoc() 
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There is not enough space on the appropriate file service to satisfy the request. 


Reading and/or writing to the Desktop is not allowed. 
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NAME 


DESKTOP LIBRARY 


dsktp__deletedoc - delete a document 


SYNOPSIS 
#include “Desktop.h” 
int 
dsktp deletedoc(ref) 
dsktp__docref ref; 


DESCRIPTION 


The dsktp_deletedoc() function is used to remove a VP document from off the desktop, from within a 
folder on the desktop, or from a nested folder. 


The ref argument is an opaque variable of the type dsktp docref. It is a handle, or pointer, to the 
document to be moved. ref was returned by an earlier call to dsktp__getdocref(). 


RETURN VALUE 


0 is returned if the call is successful, otherwise -1 is returned. The function getsigno() is used to get the 


reason for the failure. 


ERRORS 


dsktp _deletedoc() will fail if one or more of the following are true: 


Doc BadParm 


Doc TimeOut 
DT_FileChanged 


DT _FileDamaged 
DT_FilelnUse 

DT _FileNotFound 
DT Illegal 

DT _ MediumFull 
DT NoAccessRight 


One of the specified arguments is invalid. 
Inter-process communication has exceeded the maximum allowed time. 


The file has been modified during program execution such that it cannot be 
used. 


The file has been internally damaged. 

The specified file is in use by another application. 

The file was not found in the expected context. 

One of the arguments to the function call is invalid. 

There is not enough space on the appropriate file service to satisfy the request. 


Reading and/or writing to the Desktop is not allowed. 
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dsktp__enumerate 


NAME 


dsktp__enumerate - enumerate documents 
SYNOPSIS 


#include “Desktop.h” 
#include "XString.h” 


int 
dsktp enumerate(pattrn, path, depth, list) 
XString pattrn; 
XString path; 
unsigned short depth; 
dsktp__reflist *list; /* Returned */ 


DESCRIPTION 


The dsktp _enumerate() function is used to list the documents in a folder, a nested folder, or on the desktop 
that match a specified criteria. 


The pattrn argument is a text string that specifies the pattern to be used in searching for files. Two 
wildcard characters are supported: * (asterisk) and # (pound). The asterisk character matches zero or 
more characters in the file name; the pound character matches any single character in the file name. To 
use the asterisk and pound characters literally, so that they have no special significance, they must be 
preceded by a single quote. 


The path argument is a text string that specifies the full path name of the folder or nested folder in which 
to begin the search. To specify the desktop, set the value of path to NULL. A version number may be 
appended to the path name. If a version number is omitted from the path name, the most recent version is 
assumed. 


The depth argument is an integer that indicates the levels of the folder hierarchy in which to descend 
during the search for documents. The search begins with the folder specified in the path argument. A 
value of 1 indicates that only the folder specified in path is to be searched. 


The list argument is a pointer to the returned list and is of the type dsktp_reflist. It points to a structure 
whose members specify the number of objects in the list and a pointer to the handle containing the list 
itself. dsktp__reflist contains the following members: 


int len; 
dsktp__docref *refs; 


len is an integer that indicates the total number of documents that matched the search criteria. ref is a 
pointer to dsktp docref, an array containing a reference to each document that matched the search 
criteria. 7 


RETURN VALUE 


0 is returned if the call is successful, otherwise -1 is returned. The function getsigno() is used to get the 
reason for the failure. 
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dsktp _enumerate() will fail if one or more of the following are true: 


Doc BadParm 
Doc TimeOut 
DT _FileChanged 


DT FileDamaged 
DT _FilelnUse 

DT _FileNotFound 
DT_ Illegal 

DT MediumFull 
DT NoAccessRight 


One of the specified arguments is invalid. 
Inter-process communication has exceeded the maximum allowed time. 


The file has been modified during program execution such that it cannot be 
used. 


The file has been internally damaged. 

The specified file is in use by another application. 

The file was not found in the expected context. 

One of the arguments to the function call is invalid. 

There is not enough space on the appropriate file service to satisfy the request. 


Reading and/or writing to the Desktop is not allowed. 
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dsktp__getaccess 


NAME 


dsktp__getaccess - obtain the desktop information 
SYNOPSIS 
#include “Desktop.h” 
int 
dsktp getaccess(ac) 
dsktp access *ac; /* Returned */ 


DESCRIPTION 


The dsktp _getaccess() function is called to ascertain the status and access permissions of the Desktop. 


The ac argument is a pointer of the type dsktp _access.dsktp access is an enumerated variable that is set 
by the call and may have one of the following values: 


DT NONE /* Both ReadAccess and WriteAccess are FALSE */ 
DT READ /* ReadAccess is TRUE, WriteAccess is FALSE */ 
DT WRITE /* ReadAccess is FALSE, WriteAccess is TRUE */ 
DT READWRITE /* Both ReadAccess and WriteAccess are TRUE */ 
DT LOGOFF /* The Desktop is not opened */ 

RETURN VALUE 


0 is returned if the call is successful, otherwise -1 is returned. The function getsigno() is used to get the 
reason for the failure. 


ERRORS 


dsktp__getdocref() will fail if one or more of the following are true: 
Doc BadParm One of the specified arguments is invalid. 


Doc TimeOut Inter-process communication has exceeded the maximum allowed time. 
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dsktp__getdocprops 


NAME 
dsktp__getdocprops - obtain properties of a file 


SYNOPSIS 
#include “Desktop.h” 


int 
dsktp getdocprops(ref, props) 
dsktp_docref ref; 
dsktp__docprops *props; /* Returned */ 


DESCRIPTION 
The dsktp__getdocref() function is used to obtain the properties of a document on the Desktop. The 


properties associated with a Desktop document are name, version, size, creation date, creator and type. 


The ref argument is a variable of the type dsktp docref. It is a reference to the file whose properties are to 
be returned. 


The props argument is a pointer to dsktp__docprops. It is called to set the properties associated with a 
Desktop document. dsktp__docprops contains the following members: 


XString name; /* filename */ 
unsigned short vers; /* version */ 
unsigned short size; /* size in disk pages */ 
dsktp date date; /* creation date */ 
XString username; /* created by */ 
dsktp__doctype type; /* file type */ 


dsktp__date contains the following members: 


unsigned short year; /* year expressed in four digits */ 
unsigned short month; /* [1-12] */ 
unsigned short day; /* [1-31] */ 
unsigned short hour; /* [0-23] */ 


unsigned short minute;  /* [0-59] */ 
unsigned shortsecond;  /* [0-59] */ 


dsktp__doctype may have one of the following values: 


DT DOC /* document */ 

DT FOLDER /* folder */ 

DT OTHER /* other than document and folder */- 
RETURN VALUE 


0 is returned if the call is successful, otherwise -1 is returned. The function getsigno() is used to get the 
reason for the failure. 


ERRORS 


dsktp _getdocref() will fail if one or more of the following are true: 


Doc _BadParm One of the specified arguments is invalid. 
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Doc_ TimeOut 
DT _FileChanged 


DT FileDamaged 
DT _FileInUse 

DT _FileNotFound 
DT_ Illegal 
DT_MediumFull 
DT _NoAccessRight 


Inter-process communication has exceeded the maximum allowed time. 


The file has been modified during program execution such that it cannot be 
used. 


The file has been internally damaged. 

The specified file is in use by another application. 

The file was not found in the expected context. 

One of the arguments to the function call is invalid. 

There is not enough space on the appropriate file service to satisfy the request. 


Reading and/or writing to the Desktop is not allowed. 
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dsktp__getdocref 


NAME 
dsktp__getdocref - obtain a document handle 


SYNOPSIS 


#include “Desktop.h” 
#include “XString.h” 


int 
dsktp getdocref(name, vers, srcpath, ref) 
XString name; 
unsigned short vers; 
XString srcpath; 
dsktp__docref ref; /* Returned */ 


DESCRIPTION 


The dsktp__getdocref() function is used to acquire a handle, or reference, to a document on the desktop. 
The returned handle may then be passed as an argument to other related functions . 


A document is referenced as name-version pair. The name argument is a text string that specifies the 
name of the document to which a handle is desired. The ver argument is an unsigned short integer that 
indicates the version number of the document. If set to to NULL, the most recent version is assumed. 


The srcpath argument is a text string that specifies the desktop, folder, or nested folder in which the 
desired document resides. The format for specifying a folder or nested folder is the same as currently used 
to designate paths in NSFiling: folder1!v1/folder2!v2../folderN!vN. Separator characters, such as ”/” and 
1” should be escaped when they occur within folder names. They are escaped by preceding them by a 
single quote. Wildcards are not supported. If a version number is omitted from the path string, the most 
recent version is searched. To access a document that is on the desktop, set the value of srcpath to NULL. 


The ref argument is the return value and is of the type dsktp__docref. It is an array of four unsigned 
integers whose elements identify the document. 


RETURN VALUE 


0 is returned if the call is successful, otherwise -1 is returned. The function getsigno() is used to get the 
reason for the failure. 


ERRORS 


dsktp__getdocref() will fail if one or more of the following are true: 


Doc BadParm One of the specified arguments is invalid. 

Doc_ TimeOut Inter-process communication has exceeded the maximum allowed time. 

DT _FileChanged The file has been modified during program execution such that it cannot be 
used. 


DT _FileDamaged The file has been internally damaged. 
DT _FilelnUse The specified file is in use by another application. 
DT __FileNotFound The file was not found in the expected context. 


DT_ Illegal One of the arguments to the function call is invalid. 
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DT MediumFull 
DT _NoAccessRight 
SEE ALSO 


di _open(), di__finish() 
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There is not enough space on the appropriate file service to satisfy the request. 


Reading and/or writing to the Desktop is not allowed. 
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dsktp__makefolder, dsktp__deletefolder 


NAME 


dsktp__makefolder, dsktp___deletefolder - create a new folder or remove an existing folder 
SYNOPSIS 


#include “Desktop.h” 
#include "XString.h” 


int 
dsktp makefolder(name, dstpath, vers) 
XString name; 
XString dstpath; 
unsigned short *vers; /* Returned */ 


int 

dsktp deletefolder(name, vers, srcpath) 
XString name; 
unsigned short vers; 
XString srcpath; 


DESCRIPTION 


The dsktp_ _makefolder() function is used to create a folder on the desktop or within an existing folder. 


The name argument is a text string that specifies the name of the folder to be created. The dstpath 
argument is the full path to an existing folder, or nested folder, in which the new folder is to be placed. To 
specify the desktop, set the value of dstpath to NULL. 


This function returns vers, an unsigned short integer that indicates the version number of the new folder. 


The dsktp__delete() folder function is used to remove a folder from within another folder or from the 
desktop. The name argument is a text string that specifies the folder to be deleted. The vers argument is 
an integer that specifies the version number of the folder to be deleted. 


The srcpath argument is a text string that specifies the desktop, folder, or nested folder in which the 
document to be deleted resides. The format for specifying a folder or nested folder is described in 
dsktp__getdocref(). To specify the desktop, set the value of srcpath to NULL. 

RETURN VALUE 


0 is returned if the call is successful, otherwise -1 is returned. The function getsigno() is used to get the 
reason for the failure. 


ERRORS 
dsktp__*folder() will fail if one or more of the following are true: 
Doc BadParm One of the specified arguments is invalid. 
Doc TimeOut Inter-process communication has exceeded the maximum allowed time. 
DT _FileChanged i ae has been modified during program execution such that it cannot be 
used. 


DT _FileDamaged The file has been internally damaged. 


DT _FilelnUse The specified file is in use by another application. 
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DT _FileNotFound The file was not found in the expected context. 
DT_ Illegal One of the arguments to the function call is invalid. 


DT FileNotUnique The directory already contains a file of the same name (if the 
_ UniquelyNamedContents of Folder Properties is set to TRUE) or the same 
name and version (if the UniquelyNamedContents of Folder Properties is set 

to FALSE). 


DT _ MediumFull There is not enough space on the appropriate file service to satisfy the request. 


DT NoAccessRight Reading and/or writing to the Desktop is not allowed. 
SEE ALSO 


dsktp__getdocref() 
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dsktp__movedoc 


NAME 


dsktp__movedoc - move or rename a document 


SYNOPSIS 


#include "Desktop.h” 
#include “XString.h” 


int 
dsktp movedoc(ref, dstpath, name, vers) 
dsktp docref ref; 
XString dstpath; 
XString name; 
unsigned short *vers; /* Returned */ 


DESCRIPTION 


The dsktp _movedoc() function is used to move a document to a folder, a nested folder, or the desktop. This 
function may also be used as a means to rename a document. 


The ref argument is the value of dsktp__docref, an opaque variable that is a reference, or pointer, to the 
document to be moved. ref was returned by an earlier call todsktp _getdocref() or dsktp _copydoc(). 


The dstpath argument is a text string that specifies the full path name of the folder or nested folder in 
which to place the document. Refer to dsktp__getdocref() for a description of how to specify a full path. To 
specify the desktop, set the value of dstpath to NULL. 


The name argument is a text string that specifies the name of the moved document. If left NULL, the same 
name is assigned to the moved document as the source document. To rename a document, specify a 
different name but the same dstpath as that of the source document. If version numbers are omitted from 
the path string, the most recent versions are used. 


The vers argument is a pointer to an integer that indicates the version number ultimately assigned to the 
moved document. 


RETURN VALUE 


0 is returned if the call is successful, otherwise -1 is returned. The function getsigno() is used to get the 
reason for the failure. 


ERRORS 


dsktp__movedoc() will fail if one or more of the following are true: 


Doc BadParm One of the specified arguments is invalid. 

Doc TimeOut Inter-process communication has exceeded the maximum allowed time. 

DT _FileChanged The file has been modified during program execution such that it cannot be 
used. 


DT _FileDamaged The file has been internally damaged. 
DT _FilelnUse The specified file is in use by another application. 
DT_FileNotFound The file was not found in the expected context. 


DT_ Illegal One of the arguments to the function call is invalid. 
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DT _FileNotUnique 


DT __LoopinHierarchy 
DT MediumFull 
DT NoAccessRight 


SEE ALSO 


5-16 


dsktp__getdocref() 


The directory already contains a file of the same name (if the 
UniquelyNamedContents of Folder Properties is set to TRUE) or the same 
name and version (if the UniquelyNamedContents of Folder Properties is set 
to FALSE). 


The directory is the same as, or a descendant of, the file being moved or copied. 
There is not enough space on the appropriate file service to satisfy the request. 


Reading and/or writing to the Desktop is not allowed. 
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XString__intro 


NAME 


XString__intro - introductory description of XString functions 


DESCRIPTION 


Characters and strings in the VP Document Editor are structured differently than their UNIX 
counterparts. XString library functions manipulate characters and strings for use by other Document 
Interfaces Toolkit functions and for conversion between VP and UNIX structures. The XString library is 
also the means by which multinational characters and strings may be manipulated. The XString library 
supports a set of multinational character codes that adhere to the XCCS(Xerox Character Code Standard). 


The primary XString library functions perform basic services such as string copying, appending, 
separating, comparing, and searching. These functions are very similar to conventional UNIX C string 
handling functions. For example, XStrcat() is analogous to strcat(). The difference being, XStrcat() is used 
to concatenate strings that are in the XCCS format and strcat() concatenates ASCII strings. 


The XString library provides functions for conversion between XCCS 8-bit encoded strings and 16-bit 
encoded XStrings, as well as conversion between ASCII strings and XStrings. Currently, the XString 
library does not support conversion to and from EUC (Extended UNIX Code or JIS (Japanese Industrial 
Standard). 


XString data structure 
An XChar is an unsigned short integer (16 bits). Internally, it is comprised of two 8-bit bytes, where the 
first byte defines the XCCS character set and the second byte defines the XCCS character code. The 


character code determines the character’s appearance. The character set determines the character’s 
semantic meaning. 


An XString is a simple array of XChar with a a 16-bit NULL code (0x0000) at the end of the XString to act 
as the terminator. 


"TEXT 


Terminator 





Structure of XString 
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All string creation and editing functions in XString library, except XStrncpy(), assume that the resulting 
string is terminated by a NULL character. Furthermore, XCC8 (Xerox Character Code for 8 bit characters) 
is defined for a data structure of 8-bit encodings in the XCCS. XCC8 is analogous to ByteSequence in 
Mesa XString. 
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XCharset, XCharcode, XCharmake 


NAME 


XCharset, XCharcode, XCharmake - determine the character set or code used, or define character/code 
pairs 


SYNOPSIS 
#include “XString.h” 


unsigned char 
XCharset(xc); 
XChar xc; 


unsigned char 
XCharcode(xc); 
XChar xc; 


XChar 
XCharmake(set, code) 
char set; 
char code; 


DESCRIPTION 


The XChar* functions are used to invoke a character set having specific visual properties. That is, these 
functions invoke a set of characters, as well as the style in which these characters are represented. These 
character styles are referred to as character codes. 


A character code is defined as any numeric code that represents a graphic character, a rendering 
character, or a control character. The definition of a graphic character and a control character are self- 
evident. A rendering character is defined as one of the following: 

@® anon-conventional representation of a control code 

® asequence of graphic characters (i.e., ligature or accented character) 


® acontext-dependent alternate representation of a graphic character (e.g., initial, medial, or final 
form for an alphabet such as Arabic) 


® a”variant” representation of a graphic character 


In effect, a character code is the static representation of textual content. A sequence of numeric character 
codes is referred to as a string. Textual information is stored and transmitted as a sequence of numeric 
character codes. 


A character set is 256 blocks, with each block containing 256 codes. Each 16 bit character code consists of 
two 8-bit bytes, where the high-order byte is the character set code, and the low-order byte is the 
character’s code within the character set. 


The XCharset() function is used to retrieve the XChar character set (the higher 8 bits) of a character. The 
xc argument is the character for which the character set information is to be retrieved. 


The XCharcode() function is used to retrieve the XChar character code (the lower 8 bits). The xc argument 
is the character for which the character code information is to be retrieved. 


XCharmake() is used to create an XChar character of an existing character, based upon definitions 
contained within the Xerox Character Code Standard (XCCS). The variables, set and code, specify the 
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character set and the character code, respectively, that are to be used in creating the new characters. For 
example, 


xchar = XCharmake(0,’x’); 


results in an xchar being created for x. 


RETURN VALUE 


XCharset() and XCharcode() return the character code of xc. XCharmake() returns XChar character. 
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XStrcat, XStrncat 


NAME 
XStreat, Xstrncat - append to a string 


SYNOPSIS 
#include “XString.h” 


XString 
XStrcat(xs1, xs2) 
XString xs1, xs2; 


XString 

XStrncat(xs1, xs2, n) 
XString xs1, xs2; 
intn; 


DESCRIPTION 


The XStrcat() function is used to concatenate one string to the end of another string. The xs1 argument is 
the string to which the other string is to be appended. That is, xs1 is the first portion of the concatenated 
string. It is the programmer’s responsibility to ensure that sufficient storage is allocated for the data to fill 
xs1. The xs2 argument is the string to be appended. It is the second, or tailing portion of the concatenated 
string. 


The XStrncat() function is used to copy a specific number of characters from one string and append them to 
the end of another string. The xs1 argument is the string to which the copied characters are to be 
appended. It is the programmer’s responsibility to ensure that sufficient storage is allocated for the data to 
fill xs1. The xs2 argument is the string from which a specific number of characters are to be copied and 
then appended to xs1. The n argument is the number of characters that are to be copied from xs2 and 
appended to xs1. 

RETURN VALUE 


XStrcat() returns xs1. XStrncat() returns xs1. 


SEE ALSO 
XStrcpy(), XStrncpy(), XStrdup() 
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XStrcmp, XStrncmp, XStrcasecmp, XStrncasecmp 


NAME 


XStremp, XStrnemp, XStrcasecmp, XStrncasecmp - compare strings 


SYNOPSIS 


#include "XString.h” 


int 

XStrcmp(xs1, xs2) 
XString xs1, xs2; 

int 

XStrncmp(xs1, xs2, n) 
XString xs1, xs2; 
int n; 

int 

XStrcasecmp(xs1, xs2) 
XString s1, xs2; 

int 

XStrncasecmp(xs1, xs2, n) 
XString xs, xs2; 
intn; 


DESCRIPTION 


6-6 


The XStr*cmp() functions are used to compare two strings. They return negative, zero, or positive integers 
if the first string in the argument list is less than, equal to, or greater than the second string in the 
argument list. For example, in comparing the following strings: 


xs1: abcdef 
x$2: abcxyz 


XStremp() compares the characters in xs1 against xs2 on a one-by-one basis. Upon reaching the fourth 
character in xs2, a difference would be discovered. The value of XChar ”d” is 0x0064(100) and that of ”x” is 
0x78(120). XStrcmp() then returns "d - x”, which is -20 in decimal. 


Comparisons are done in the order specified in the Xerox Character Code Standard (XCCS). 
The XStrcmp() function is used to compare two strings, xs1 and xs2. 


The XStrncmp() function is used to compare a portion of one string against another string. The xs1 
argument is the string from which the first n characters are to be compared against the first n characters 
of the string specified in the xs2 argument. 


The XStrcasecmp() function is used to compare two strings, while ignoring the case of ASCII characters. 
That is, upper-case characters are equal to the lower-case equivalent characters. The xs1 and the xs2 
arguments are the two strings to be compared. Non-ASCII characters will be compared in accordance to 
the order specified by the XCCS. 


The XStrncasecmp() function is used to compare a portion of one string against another string, while 
ignore the case of ASCII characters. The xs1 argument is the string from which the first n characters are 
to be compared against the first n characters of the string specified in in the xs2 argument. Non-ASCII 
characters will be compared in accordance to the order specified by the XCCS. 
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RETURN VALUE 


positive integer: xs1>xs2 
zero: xs1 = xs2 
negative integer: xs1<xs2 


SEE ALSO 
XStrlexcmp(), XStrnlexcmp(), XStrcaselexcmp(), XStrncaselexcmp() 
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XStrcpy, XStrncpy, XStrdup 


NAME 


XStrepy, XStrnepy, XStrdup - copy string 


SYNOPSIS 


#include “XString.h” 


XString 
XStrcpy(xs1, xs2) 
XString xs1, xs2; 


XString 

XStrncpy(xs1, xs2, n) 
XString xs1, xs2; 
int n; 


XString 
XStrdup(xs1) 
XString xs1; 


DESCRIPTION 


The XStrepy() function is used to copy a specific string into a virtual memory storage area, defined by the 
user. The argument xs2 is the text string to be copied. The argument xs1 is a pointer to the storage area 
that is to receive the string. It is the programmer’s responsibility to ensure that sufficient storage is 
allocated for the data to fill xs1. 


The XStrncpy() function is used to copy a specific number of characters in a text string. The argument xs2 
is the text string to be copied. The argument xs1 is a pointer to the storage area that is to receive the 
string. It is the programmer’s responsibility to ensure that sufficient storage is allocated for the data to fill 
xs. 


The argument n is an integer that specifies the number of character in the xs2 argument to copy. Copying 
begins with the first letter of the text string and proceeds to the last. If the number of characters to copy, n, 
is greater than than the length of the string, xs2, then the entire string, including the NULL character, will 
be copied. If the number of characters to copy is less than or equal to the number of characters in the 
string, the string will be copied and the terminating NULL character truncated. 


The XStrdup() function is used to copy a text string into a storage area and return a pointer to that area. 
The xs1 argument is the string to be copied. Memory space for the copy is reserved by malloc. If malloc 
fails in memory reservation, a NULL pointer is returned. 


RETURN VALUE 


XStrepy() and XStrncpy() return xs1. The return value of XStrdup() is xs1, a pointer to the duplicate 
string. A NULL pointer is returned if malloc fails in memory allocation. 


SEE ALSO 
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XStrceat(), XStrncat() 
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XStrien 


NAME 
XStrlen - string length 


SYNOPSIS 
#include “XString.h” 


int 
XStrlen(xs); 
XString xs; 


DESCRIPTION 


The XStrlen() function is used to determine the logical length of an XString character. The returned value 
will specify the number of characters in the string as an integer. The returned character length will not 
include the terminating NULL character. 


The xs argument is the string whose length is to be determined. 


RETURN VALUE 
The character length of xs. 
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XStrlexcmp, XStrnlexcmp, XStrcaselexcmp 


NAME 


XStrlexcmp, XStrnlexcmp, XStrcaselexcmp - compare strings lexicographically 


SYNOPSIS 


#include “XString.h” 


int 

XStrcaselexcmp(xs1, xs2, sortorder) 
XString xs1, xs2; 
SortOrder sortorder; 


int 

XStrlexcmp(xs1, xs2, sortorder) 
XString xs1, xs2; 
SortOrder sortorder; 


int 

XStrncaselexcmp(xs1, xs2, sortorder, n) 
XString xs1, xs2; 
SortOrder sortorder; 
intn; 


int 

XStrnlexcmp(xs1, xs2, sortorder, n) 
XString xs1, xs2; 
SortOrder sortorder; 
intn 


DESCRIPTION 


The XStr*lexcmp() functions are used to lexicographically compare two strings. They return negative, 
zero, or positive integers if the first string in the argument list is lexicographically less than, equal to, or 
greater than the second string in the argument list. Comparisons are done in accordance to the order 
specified by sortorder. 


The XStrlexcmp() function is used to compare two strings, xs1 and xs2, according to the order specified in 
sortorder. sortorder is described in detail in the document, Multinational Programming Considerations. 


The XStrnlexcmp() function is used to compare the first n characters of xs1 against xs2, based upon the 
value of sortorder. 


The XStrcaselexcmp() function is used to compare two strings, while ignoring the case of ASCII characters 
and while sorting the character strings in the order specified in sortorder. Upper-case characters will be 
equal to the lower-case equivalent characters. The xs1 and the xs2 arguments are the two strings to be 
compared. Non-ASCII characters will be compared in accordance to the specified lexicographical order 
defined by sortorder. 


The XStrncaselexcmp() function is used to compare a portion of one string against another string, while 
ignoring the case of ASCII characters. The xs1 argument is the string from which the first n characters are 
to be compared against the string specified in the xs2 argument, according to the specified sort order, 
sortorder. 
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sortorder is the value of SortOrder, an enumerated type that may contain one of the following values: 
STANDARD, DANISH, SPANISH, SWEDISH 


Please refer to the table below for a description as to the category each language falls into: 


(English) 
(French) 


United Kingdom Standard 


















RETURN VALUE 

1: xsi > xs2 

0: xs1 = xs2 

=2: RPC function, cint__create() failed. 

-3: RPC function, cint__call() failed. 

-4: UNIX standard function, gethostname() failed. 

-5: The length of xs1 or xs2 exceeds 8192 bytes. 
SEE ALSO 


XStremp(), XStrncmp(), XStrcasecmp(), XStrncasecmp() 
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XStrchr, XStrrchr, XStrpbrk 


NAME 


XStrehr, XStrrchr, XStrpbrk- search for a character 


SYNOPSIS 


#include “XString.h” 


XString 

XStrchr(xs, xc) 
XString xs; 
XChar xc; 


XString 

XStrrchr(xs, xc) 
XString xs; 
XChar xc; 


XString 
XStrpbrk(xs1, xs2) 
XString xs1, xs2; 


DESCRIPTION 


The XStrchr() function is used to parse a string in search of a specific character. It starts the search at the 
beginning of the string and proceeds towards the end. The xs argument is the string to be searched. The xc 
argument is the character to be found in the string. If the specified character is found, a pointer to the first 
occurrence of the character is returned. If the specified character is not found, a NULL pointer is returned. 


The XStrrchr() function, like XStrchr(), searches a string for a character. It starts the search at the end of 
the string and proceeds towards the beginning. If the specified character is found, a pointer to the first 
occurrence of the character in the string is returned. If the specified character is not found, a NULL pointer 
is returned. 


For example, to find character ”x” in the following example: 
abcexdefxg 


XStrchr() will return a pointer to the ”x” which is the third character from the left. XStrrchr() will return a 
pointer to the ”x” which is the second character from the right. 


The XStrpbrk() function is used to search a string for the occurrence of any character contained within 
another string. The xsl argument is the string to be searched. The xs2 argument is the string from which 
each character is extracted and then compared against each character in xs1. The first character in xs2 is 
parsed, placed in a buffer and then compared against each character in xs1. The comparison stops upon the 
first match. The system then returns a pointer to the first occurrence of the matching character in xs1. If 
the specified character is not found, a NULL pointer is returned. 


RETURN VALUE 


A pointer to the character’s location, if it is found. A NULL pointer, if the character is not found. 


SEE ALSO 


XStrsch() 
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XStrsch 


NAME 


XStrsch - search for a string 


SYNOPSIS 
#include "XString.h” 
XString 
XStrsch(xs1, xs2) 
XString xs1, xs2; 
DESCRIPTION 


The XStrsch() function is used to determine if a string is contained within another string. It starts the 
search at the beginning of the string and proceeds towards the end. The xs1 argument is the main string. 
The xs2 argument is the string that you would like to find in xs1. If the search is successful, the system 
returns a pointer to the first occurrence of xs2 in xs1. Otherwise, a NULL pointer is returned. 


RETURN VALUE 
A pointer to the string, if it is found. A NULL pointer, if it is not found. 


SEE ALSO 
XStrchr(), XStrrchr(), XStrpbrk() 
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XStrsep 


NAME 


XStrsep - separate a string into tokens 


SYNOPSIS 
#include "XString.h” 


XString 

XStrsep(xs1, xs2, xc) 
XString  xs1,xs2; 
XChar *xc; 


DESCRIPTION 


The XStrsep() function is used to separate a string into tokens based upon one or more delimiter 

characters. The xs1 argument is the string to be separated. The xs2 argument is a string containing one or 

more delimiter characters. Each character within xs2 is considered as a delimiter. Separator characters 
99 99 99999 99,9? 


may be standard delimiters, such as ”,”, , and ”;”, or they be any desired text characters. The xc 
argument is a pointer to the returned delimiter character. 


This function returns a pointer to the first character of the first token and returns the delimiter character 
to xc. If the delimiter characters specified in xs2 can not be found in string xs1, then the system returns 
the entire string as one token and sets xc to NULL. When xs1 can not be further separated into tokens, a 
NULL pointer is returned. 


After completing a call to XStrsep(), the original string specified as the argument xs1 will no longer exist. 


RETURN VALUE 


Pointers to the first character of each separated token. 
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XStrfromASC, XStrtoASC 


NAME 
XStrfromASC, XStrtoASC - convert ASCII and XString strings 


SYNOPSIS 
#include “XString.h” 


XString 
XStrfromASC(xs, s) 
XString xs; 

char *s; 


XString 
XStrtoASC(xs, s, c) 
XString xs; 
char *s; 

char ¢c; 


DESCRIPTION 


The XStrfromASC() function is used to convert the ASCII string pointed to by s to XString xs. The return 
value will be xs. It is the programmer’s responsibility to insure that sufficient storage space is allocated for 
xs. xs will require (2X s byte length) + 2. 


Basically, this function does not convert control coeds. If a control or 8-bit code (a code that belongs to the 
group on the shift-out side) is in the ASCII string, s, it will be simply extended to a 16-bit code and copied 
into xs. If the resultant code is identical to an XCCS code of the character set 0, it will be expressed as a 
VP character in VP documents. If it is identical to a control code like a tab in VP, it will be used as is. If it 
is not defined in VP, it will be expressed as a black square. An exception is OxFF, which will be converted 
to 0x007F and copied into xs. It is the user’s responsibility to process these codes correctly. Note the 


following codes. 
0x09 (11B) — Tab (Tab) 
0x0D (15B) — New Line (NewLine) 
0x1D (35B) — New Paragraph (NewPara) 
0x89 (211B) — Paragraph Tab (ParaTab) 
0x87 (207B) — Page Number 
0Ox8E (216B) — Table of contents mark (left) 
0Ox8F (217B) — Table of contents mark (right) 


The XStrtoASC() function is used to convert the XString xs into an ASCII string s. During the conversion, 
characters that do not have ASCII equivalents are replaced by the character signified by c. This function 
returns 0, if all the characters in xs were successfully converted to ASCII. Otherwise, it returns the 
number of non-ASCII characters in xs. 


It is the programmer’s responsibility to assure that sufficient storage is allocated for $s. $ will require (xs 
character length + 1 byte) for storage. 


RETURN VALUE 
xs is returned by XStrfromASC. XStrtoASC returns the number of non-ASCII characters in xs. 
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XStrfromxXCCs, XStrtoxCC8 


NAME 
XStrfromXCC8, XStrtoXCC8 - convert between XCCS 8-bit encoded string and XString 


SYNOPSIS 
#include "XString.h” 


XString 

XStrfromXCC8(xs, xcc8, len, prefix) 
XString xs; 
XCC8 xcc8; 
int len; 
int prefix; 

int 

XStrtoXCC&8(xs, xcc8) 

- XString xs; 

XCC8 xcc8; 


DESCRIPTION 


The XStrfromXCCa() function is used to convert an XCCS 8-bit encoded string into an XString string. The 
xs argument is the storage area in which to place the converted XString string. The xcc8 argument is the 
XCCS 8-bit encoded string that is to be converted. The len argument specifies the length in bytes of xcc8. 
The prefix argument should be set to 0 if xcc8 is a standard 8-bit encoded string. The encoded string is 
considered to be ’standard” if the first character begins with the character set 0 or with character set 
select (Oxff). If the first character in xcc8 begins with a character code that indicates the use of a non-zero 
character set, the value of the prefix argument should also use that same character set. prefix should be -1 
if the first character of xcc8 begins with a 16-bit code. A successful conversion returns xs. An unsuccessful 
conversion returns a NULL pointer. 


To calculate sufficient storage resources for xs, allow (2* xcc8 byte length) + 2 bytes. 


The XStrtoXCC&() function is used to convert an XString string into a compact XCCS 8-bit encoded string. 
The xs argument is the value of the XString string to be converted. The xcc8 argument is the return value 
that is to contain the XCCS 8-bit encoded string. 


In the XCCS system, a 16-bit encoded representation is possible by placing two character set selects (Oxff) 
plus 0 (total of three bytes) at the point where the 16-bit encoding representation starts. Therefore, 
XStrtoXCCa() first compares the length of the 8-bit and 16-bit ({Oxff,Oxff,0x0] at the head of xs) encoding 
representations that XStrtoXCC8() would get after converting xs. After which, XStrtoXCC&() converts xs 
into xcc8 in the shorter representation. 


The first byte of the converted xcc8 begins, either, with a character code having a character set 0, or with 
character set select 0 (Oxff). The return code will be the byte length of the converted xcc8 string. 


To calculate sufficient storage resources for xcc8, allow (2 * xs character length) + 3 bytes for storage. 


XCC8 requires data structures of 8-bit encodings in a XCCS format. XCC8 is analogous to ByteSequence 
in Mesa XString. 


RETURN VALUE 


XStrtoXCC&() returns the byte length of xcc8. XStrfromXCC8() returns a NULL pointer, if xcc8 encoding is 
invalid or xs is invalid, otherwise it returns xs. 
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NAME 


SS EE SP DRA 
7. Document IC Signals 


getsigno - retrieve the number of an error 


SYNOPSIS 


#include “Signals.h” 


int 
getsigno() 


DESCRIPTION 


When a function returns -1, getsigno() is called to determine the cause for the failure. 


The getsigno() function takes no arguments and its return value indicates the reason for the failure. 


The following is a list of error numbers and the corresponding text names, as specified in ’Signals.h”: 


/* Signals from Document IC Toolkit operations */ 


4096 (0x1000) 
4097 (0x1001) 
4098 (0x1002) 
4099 (0x1003) 
4100 (0x1004) 
4101 (0x1005) 
4102 (0x1006) 
4103 (0x1007) 
4104 (0x1008) 


4105 (0x1009) 


Doc_ ContainerFull 
Insufficient space for appending to this container. 


Doc__DocumentF ull 
Insufficient space in the document. 


Doc__ReadonlyDoc 
Document opened in ReadOnly mode. 


Doc__OutOfDiskSpace 
Insufficient disk space for the operation. 


Doc__OutOfVM 
Insufficient virtual memory for the operation. 


Doc__ObjIllegalInCont 
Attempted to add an object of an unsupported type to a container. 


Doc__BadParm 

One of the arguments specified is invalid. 
Doc__Unimpl 

This function is not supported. 


Doc__OutOfRoomForGraphics 
Insufficient space in the document to insert graphics objects. 


Doc__TableTooWide 
The specified table is too wide to fit in the document. 
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4106 (0x100a) 


4107 (0x100b) 


4108 (0x100c) 


4109 (0x100d) 


4110(0x100e) 


Doc__TableTooTall 
The specified table is too tall to fit in the document. 


Doc__TableHeaderTooTall 
The specified headers are too tall. 


Doc__TimeOut 
Timeout has occurred during inter-process communication. 


Doc_ IllegalHandle 
The handle specified is invalid. 


Doc__NoAccessRight 
Reading and/or writing to the document is not allowed. 


/* Signals from XString operations */ 


8192 (0x2000) 


XS__ Illegal 
The specified XString is invalid. 


/* Signals from Desktop operations */ 


16384 (0x4000) 


16385 (0x4001) 
16386 (0x4002) 
16387 (0x4003) 
16388 (0x4004) 


16389 (0x4005) 


16390 (0x4006) 
16391 (0x4007) 


16392(0x4008) 


DT__FileChanged 

While the function was executing, the file changed in such a way that execution 
could not continue. This condition may occur, for example, when 
dsktp enumerate() is called and the order of the files contained in a folder or on 
the desktop changes. 


DT__FileDamaged 
A file is internally damaged in some way. 


DT__FileInUse 
The specified file is in use by another application. 


DT_ FileNotFound 
A file was not found in the expected context. 


DT_ Illegal 
One of the arguments passed to the desktop interface is invalid. 


DT__FileNotUnique 

The directory already contains a file with the same name (if the 
UniquelyNamedContents of Folder Properties is set to TRUE) or the same name 
and version (if the UniquelyNamedContents of Folder Properties is set to FALSE). 


DT__LoopInHierarchy 
The directory is the same as, or a descendant of, the file being moved or copied. 


DT__MediumF ull 
There is not enough space on the appropriate file service to satisfy the request. 


DT_ NoAccessRight 
Reading and/or writing to the desktop is not allowed. 


/* Signals from implementation failures */ 


32767 (Ox7fff) 
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IMPL_ SIG 
An unimplemented module has been encountered. 
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/* Place holder for unidentified signals */ 


32766 (0x7ffe) OTHER_SIG 
The default signal that is displayed when an error occurs that cannot be addressed 
by any of the preceding signals. 


RETURN VALUE 


The return value of getsigno() is the reason for the most recent failure of all but XNS functional calls. 
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XNS__intro 


NAME 


XNS__intro - introductory description of XNS interchange functions 


DESCRIPTION 


The XNS toolkit library is the means by which UNIX/C programmers may interface with Xerox XNS 
servers. The XNS toolkit library contains functions, referred to as stubs, that allow calls to be made to the 
clearinghouse server, the authentication server, file servers, the print server, mail servers, and the 
Gateway Access Protocol (GAP) server. Xerox System Integration Standards contain protocol information 
on these servers. The standards described in these books, however, define the protocols with respect to the 
Xerox Mesa language. C programmers may still benefit from the descriptions in these books because Mesa 
and C functions are similar in many respects. Function calls in C require the same parameters as the 
equivalent Mesa functions. These parameters are of the same type in both programming languages. The 
exception is, the C representation of a function contains two extra parameters. They are Connection and 
BDTprocptr. 


Connection 


Every XNS function called by a C application must contain a value for the parameter Connection. This 
parameter is the courier connection number of the XNS server to which the C application is attempting 
communication. Therefore, for example, depending upon the XNS server number entered, it is possible to 
direct a C application to communicate with a specific printer. 


The number to be supplied as the value of the _ Connection parameter may be obtained by entering the 
following code in the C application: 


COURIERFD connected; 
char *hostnameptr; 


if (!(connected = cour__establish__conn(hostnameptr))) { 
fprintf(stderr, "\t\\tCOURIER CONNECTION FAILED!!!\n"); 
return; 


} 


In the example code above, connected is the return value of the cour__esta blish_ _conn function supplied by 
libcourier.a (a library that you must link with to use XNS functions). 


hostnameptr is a string that contains the name of the desired server. For example, if you have access to 
the Xerox organization and the Sunnyvale domain, and you wish to access a printer called BCobain in that 
domain, then: 


hostnameptr = "BCobain:Sunnyvale: Xerox" 


would be be the proper format for specifying the printer. If a connection to the host does not occur, an error 
message will be printed. 
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some XNS functions do not require a valid value for. Connection. Those functions requiring a valid 
__Connection value are described as appropriate. The remaining functions should be set to NULL. 


__BDTprocptr 


Every XNS function also requires a value for the parameter _ BDTprocptr. For those functions that 
transfer bulk data, this parameter is the name of the function that performs the bulk-data transfer. This 
bulk data function is created by the C programmer. As an example, to print 4 ‘UNIX file the C code ee ye 
contain the following call: —— es N oO 7 G6 was TEx fate } 


printresult = Print(printconnected, SendSource, Bulk Datat~immediateSource, attributes, options); 


Two parameters of special importance are SendSource and BulkData1 immediateSource. SendSource is 
the name of the user-defined C function that sends print data from the UNIX environment to the XNS 
printer defined by the printconnected parameter, the courier connection number for the printer. The code 
you write to define SendSource may be as follows: 


int 


SendSource (bdtconnection) 
COURIERFD bdtconnection; 


char * buf; 

int buflen; 

int count; 

extern int errno; 

int len; 

char _local__buf[BUFSIZ]; 


len = sizeof(local__buf) < < 3; 

if (len <= 0 || !(buf = malloc(len))) { 
buf = local_ buf; 
len = sizeof(buf); 


} 
while ((count = read(ipfile, buf, len)) > 0) { 
if (cour__bdt__write(bdtconnection, buf, count) < count) { 
if (buf != local__buf) 
free(buf); 
return BDT_WRITE_ ABORT; 


} 

} 

if (buf != local__buf) 
free(buf); 


return (count > = 0)? BDT_WRITE_ FINISHED: BDT_WRITE__ABORT; 
} 


When transferring bulk data, another parameter of type Sink or Source must also be supplied. These two 
types are bulk data types. They direct the function to source data from the UNIX environment or sink data 
to the UNIX environment. To send data from UNIX to XNS, use BulkData1 immediateSource. To 
retrieve data from XNS back to UNIX, use BulkData1 _immediateSink. _ 


A valid value for this parameter is only required if the function transfers bulk data. If it does not, set the 
value of this parameter to NULL. 
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Error Handling 


The code to trap errors generated by XNS functions must be defined by the user. Each XNS function has a 
specified set of errors that it may return. The Standards book for the respective protocol explains each 
error. This manual lists the possible errors each function may return. Two errors not described in either 
the Gray Book or this manual are courier-generated errors: REJECT_ERROR and SYSTEM_ ERROR. 
These two errors may be generated by any XNS function. The following code may be inserted in the C 
program to catch these errors: 


#include <courier/except.h> 


int secondlevelerror, syserror; 
Cardinal probnum,; 


secondlevelerror = 0; 
syserror = 0; 


DURING 
StatusResult = GetPrinterStatus(getprintstatusconnected,N ULL); 
HANDLER { 
char * msg; 
switch (Exception.Code) { 
case Service Unavailable: 
msg = "GetStat: Service unavailable"; 
break; 
case SystemError: 
msg = "GetStat: System Error"; 
break; 
case Undefined: 
msg = "GetStat: Undefined error”; 
probnum = CourierErrArgs(UndefinedArgs,problem); 
secondlevelerror = 1; 
break; 
case REJECT__ERROR: 
switch (CourierErrArgs(rejectionDetails, designator)) { 
case 0: 
msg = "GetStat: REJECT: noSuchProgramNumber"; 
break; 
case 1: 
msg = "GetStat: REJECT: noSuchVersionNumber"; 
break; 
case 2: 
msg = "GetStat: REJECT: noSuchProcedureValue"; 
break; 
case 3: 
msg = "GetStat: REJECT: invalidArgument”"; 
break; 
default: 
msg = "GetStat: REJECT: unknown error"; 
secondlevelerror = 1; 
probnum = CourierErrArgs(rejection Details, designator); 
break; 
; 
break; 
case SYSTEM __ERROR: 
msg = "GetStat: Connection Error"; 
syserror = 1; 
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break; 
default: 
msg = "GetStat: Some random error"; 
secondlevelerror = 1; 
probnum = Exception.Code; 
break; 
} 
fprintf (stderr,"\t\t\tError: %s\n", msg); 
if (syserror) { 
syserror = 0; 
fprintf (stderr,"\t\t\t%s\n", Exception. Message); 


if (secondlevelerror) { 
secondlevelerror = 0; 
fprintf (stderr,"\t\t\tProblem number: %d\n", probnum); 


} 
}END_HANDLER; 


When an error occurs, the XNS function will return a code number and sometimes a problem number. The 
above code switches on the error code number in order to print out the user-defined error message. If the 
error also returns a problem number, you can determine the cause of the error by calling CourierErrArgs(). 
Refer to the respective Standards book for more details. 


Be sure to include except.h in the application. This header file defines the macros DURING, HANDLER, 
and END_HANDLER. 


Header Files 
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Each XNS service has two particular header files associated with it: [service]__de.h and [service].h, where 
[service] represents the name of the service. For example the printing service, which would be 
Printing3__de.h and Printing3.h. Your application should include one or the other, but not both. The 
[service]__de.h header files simplifies typing. It has define statements that eliminate the need for prefixing 
function and error statements with the service name. [service].h is the "raw" header file. If you include 
this header file, you must prefix the name of the service to each function or error name in the application. 
For example, the function ChangeStrongKey() may be specified in one of two ways: If the header file used 
is Authentication2.h, the function must be specified as Authentication2 ChangeStrongKey(). If the header 
file used is Authentication2.de.h, then the function may be specified as ChangeStrongKey/(). 
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Authentication2__ChangeStrongKey, _ ChangeSimpleKey 


NAME 


ChangeStrongKey, ChangeSimpleKey — change a user's strong or simple key 


SYNOPSIS 


#include <courier/Authenti2 de.h> 
#include <courier/except.h> _ 


void 
ChangeStrongKey( Connection, BDTprocptr, credentials, verifier, newKey) 
COURIERFD Connection; —_ 
int(* BDTprocptr)(); 
Credentials credentials; 
Verifier verifier; 
Block newKey; 


void 
ChangeSimpleKey( Connection, BDTprocptr, credentials, verifier, newKey) 
COURIERFD Connection; 
int(* BDTprocptr)(); 
Credentials credentials; 
Verifier verifier; 
Cardinal newKey; 


DESCRIPTION 
The ChangeStrongKey() function is used to change a strong key that is registered with the Authentication 
Service. 


The strong credentials and verifier arguments identify the client for whom the key is to be changed. The 
newKey argument is the strong key that has been encrypted using the ECB mode of DES, and the 
conversation key that is contained in the credentials. The encryption and decryption of the strong key is 
performed by user-defined code. 


The ChangeSimpleKey() function is used to change a simple key that is registered with the Authentication 
Service. 


The simple credentials and verifier arguments identify the user for whom the simple key is to be changed. 
The newKey argument is the unencrypted new key that is to be registered. The newkey must be hashed 
by the user. 


Use of these functions is contingent upon how the Internet is administered. If you are unable to change a 
strong or simple key via remote function calls, it may be due to the Internet administrative rules. 


RETURN VALUE 


These functions return void. 


ERRORS 
Reports [AuthenticationError[problem], CallError[problem]] 
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SEE ALSO 
CreateStrongKey(), CreateSimpleKey() 
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Authentication2__CheckSimpleCredentials 


NAME 


CheckSimpleCredentials — verify a user’s identity 


SYNOPSIS 


#include <courier/ Authenti2__de.h> 
#include <courier/except.h> 


void 
CheckSimpleCredentials( Connection, BDTprocptr, credentials, verifier) 
COURIERFD Connection; _ 
int(* BDTprocptr\(); 
Credentials credentials; 
Verifier verifier; 


DESCRIPTION 


The CheckSimpleCredentials() function is used to verify that the correct password has been submitted to 
the Authentication Service. The Authentication Service compares the simple key that is registered for the 
initiator against the simple key in the verifier. The credentials are used to specify the Clearinghouse in 
which the initiator is registered. 


The credentials and verifier arguments must be the simple credentials and verifier of the initiator. Simple 
credentials are the initiator’s ThreePartName, specified as a text string. Simple verifier is the result of a 
hashing algorithm applied by the Authentication Service upon the initiator's password. 


RETURN VALUE 


This function returns a structure called CheckSimpleCredentialsResults. Its one member is a Boolean 
value. A value of TRUE indicates that the simple key registered for the initiator and the simple key 
specified in the verifier match. 


ERRORS 
Reports [AuthenticationError[problem], CallError[problem]] 
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Authentication2__CreateStrongKey, _CreateSimpleKey 


NAME 


CreateStrongKey, CreateSimpleKey - register a new strong or simple key 


SYNOPSIS 


#include <courier/Authenti2 de.h> 
#include <courier/except.h> _ 


void 
CreateStrongKey( Connection, BDTprocptr, credentials, verifier, name, key) 
COURIERFD Connection; ~ 
int(* BDTprocptr)(); 
Credentials credentials; 
Verifier verifier; 
ThreePartName name; 
Key key; 


void 
CreateSimpleKey( Connection, BDTprocptr, credentials, verifier, name, key) 
COURIERFD Connection; 
int(* BDTprocptr)(); 
Credentials credentials; 
Verifier verifier; 
ThreePartName name; 
Cardinal key; 


DESCRIPTION 


The CreateStrongKey() function is used to register a strong key with the Authentication Service. 


The credentials and verifier specified must be the strong credentials and strong verifier of a privileged 
user. The Authentication protocol for these two is described below. name is the user name as known by the 
Clearinghouse. The key is the strong key to be registered with the Authentication Service. It will be 
encrypted in the ECB mode of DES, using the conversation key contained in the credentials. 


Strong credentials consist of data which has been encrypted using the National Bureau of Standards’ Data 
Encryption Standard (DES). A key is an array comprised of 4 16-bit wide words, where the least 
significant bit is assigned as the parity bit, thus leaving 56 bits for unconstrained data. The least 
significant bit of each octet is set so as to make the parity of each octet odd. 


The CreateSimpleKey() function is used to register a new simple key with the Authentication Service. A 
simple key is a simple password that has been hashed according to the algorithm specified in the Xerox 
Authentication Protocol manual. Only a privileged user may register a new key. 


The credentials and verifier arguments must be the strong credentials and verifier of a privileged user. 
The name argument specifies the intended user of the key. The key argument is the unencrypted key that 
is to be registered. 


RETURN VALUE 
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These functions return void. 
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ERRORS 
Reports [AuthenticationError[problem], CallError[problem]] 


SEE ALSO 
ChangeStrongKey(), ChangeSimpleKey(), GetStrongCredentials() 
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Authentication2__DeleteStrongKey, _DeleteSimpleKey 


NAME 
DeleteStrongKey, DeleteSimpleKey -— delete a user’s strong or simple key 


SYNOPSIS 


#include < courier/Authenti2__de.h > 
#include <courier/except.h > 


void 
DeleteStrongKey( Connection, BDTprocptr, credentials, verifier, name) 
COURIERFD Connection; 
int(* BDTprocptr)(); 
Credentials credentials; 
Verifier verifier; 
ThreePartName name; 


void 
DeleteSimpleKey(_ Connection, _BDTprocptr, credentials, verifier, name) 
COURIERFD __Connection; 
int(*__ BDTprocptr)(); 
Credentials credentials; 
Verifier verifier; 
ThreePartName name; 
DESCRIPTION 
The DeleteStrongKey() function is used to delete a strong key that is registered with the Authentication 
Service. 


The credentials and verifier arguments must be the strong credentials and verifier of the key’s owner or of 
a privileged user. The name argument specifies the user for whom the key is to be deleted. 


The DeleteSimpleKey() function is used to delete a simple key that is registered with the Authentication 
Service. 


The credentials and verifier arguments must be the simple credentials and verifier of the possessor or of a 
privileged user. The name argument specifies the user for whom the key is to be deleted. 


RETURN VALUE 


These functions return void. 


ERRORS 
Reports [AuthenticationError[problem], CallError[problem]] 


SEE ALSO 
CreateStrongKey(), CreateSimpleKey() 
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Authentication2__GetStrongCredentials 


NAME 


GetStrongCredentials — acquire privileged user permission 


SYNOPSIS 


#include < courier/Authenti2__de.h > 
#include <courier/except.h> 


GetStrongCredentialsResults 
GetStrongCredentials( Connection, BDTprocptr, initiator, recipient, nonce) 
COURIERFD Connection; 
int(* BDTprocptr)(); 
ThreePartName initiator; 
ThreePartName recipient; 
LongCardinal nonce; 


DESCRIPTION 


The GetStrongCredentials() function is used to create credentials in order to prove one’s identity to a 
specified communications partner (i.e., recipient). Once created, the privileged user can act on behalf of 
any user within the same organization and domain. To get StrongCredentials you must have a strong key 
registered with the Authentication Service and you must know how to decrypt the results. 


It is sometimes necessary to authenticate oneself to the Authentication Service, such as when modifying a 
strong key or fetching credentials through a proxy. To authenticate oneself, you must supply the name of 
the Authentication Service. Since any instance of the Authentication Service may be specified, the service 
is accessible through a ”wellknown” name. This wellknown name may be used regardless of the instance 
actually being accessed. The wellknown name of the Authentication Service is Authentication 
Service:CHServers:CHServers. 


A sender, called the initiator, attempts to authenticate itself to a receiver, called the recipient. To do this 
the sender contacts the Authentication Service, via this function, and supplies to the Service the names of 
both parties and a random number, called a nonce. The nonce is a check mechanism that insures the 
validity of the Authentication Service. If the sender is properly registered with the Authentication 
Service, this function will return credentials, the nonce, the receiver’s name and conversation key. All 
four are encrypted. The decrypted credentials are used by other functions, such as DeleteSimpleKey(). The 
conversation key is not passed to any function. It is used to encrypt verifiers that are later passed to those 
functions requiring strong verifiers. 


The initiator argument is the distinguishing name, or alias, of the user that wishes to be authenticated. 
The recipient argument is the distinguishing name, or alias, of the recipient to whom the initiator is 
proving his identity. 


RETURN VALUE 


This function returns a structure called GetStrongCredentialsResults. Its one member, 
credentialsPackage, isoftypeT r14 2 2. It hasbeen encrypted with the initiator’s key. Once decrypted 
with the initiator’s key, it will contain credentials that have been encrypted with the recipient’s key, of 
which only the recipient may decrypt. It will also contain a nonce, the recipient’s name, and a 
conversation key. Once the credentialsPackage has been decrypted it is possible for the initiator to view 
the nonce, the recipient’s name, and conversation key.The initiator may not view the credentials because 
itis still encrypted with the recipient’s strong key. 
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ERRORS 
Reports [CallError[problem]] 
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Clearinghouse2__ AddGroupProperty 


NAME 
AddGroupProperty - add a group type property to an object 


SYNOPSIS 


#include <courier/Clearing2 de.h> 
#include <courier/except.h> 


AddGroupPropertyResults 
AddGroupProperty( Connection, BDTprocptr,name, newProperty, membership, agent) 
COURIERFD Connection; 
int(* BDTprocptr)(); 
ThreePartName name; 
LongCardinal newProperty; 
BulkData1 Descriptor membership; 
Authenticator agent; 


DESCRIPTION 


The AddGroupProperty() function is used to add a new group type property to an object. The value of a 
group type property is understood by the Clearinghouse to be a sequence of Clearinghouse names called 
members. 


A Clearinghouse object is comprised of three parts: a property number (ID), a property type, and a value. 
A property is primarily used to hold a network location, or a list of other object names. Given an object 
name and a property number, the Clearinghouse will return the value of that property, which will be 
either a block of data (if the property type is item), or a list of names (if the property type is group). The 
Clearinghouse does not inspect item properties, therefore they may consist of any data the client wishes. 
The group property, on the other hand, is inspected and recognized by the Clearinghouse, therefore each 
group property must contain a sequence of Clearinghouse names called members.The name argument is 
the Clearinghouse name of the object. It may be in the form of either the actual name of the object or its 
alias. UNIX wildcards may not be used in specifying any part of the object name. 


The name argument is comprised of three strings that identify the organization, domain, and name of an 
object. Wildcards may not be used to specify any portion of this argument. It may be a distinguished name 
or an alias. 


The newProperty argument identifies the group type property that is to be added to an object. 


The membership argument is a Bulk Data Transfer parameter that specifies the source that supply the 
list of names in accordance to the Bulk Data Transfer Protocol. This list of names provides the initial 
value of the new group type property. That is, the group type property is initialized with zero or more 
members as specified by the source. The data sent via membership is of type SegmentOfThreePartName. 
Wildcard characters may occur in any part of each name, but the characters will not have wildcard 
significance. They will be interpreted as regular characters. 


The agent argument is a structure whose two members contain the client’s credentials and verifier. 


RETURN VALUE 


This function returns a structure called AddGroupPropertyResults. Its one member, distinguishedObject, 
is of type ThreePartName. It is the full name of the object that received the new group type property. 
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ERRORS 


Reports [ArgumentError[problem], AuthenticationError[problem], CallError[problem], 
PropertyError[problem], UpdateError[problem], WrongServer] 


SEE ALSO 
ListProperties() 
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Clearinghouse2__AdditemProperty 


NAME 
AddItemProperty -- add a item type property to an object 


SYNOPSIS 


#include <courier/Clearing2 de.h> 
#include <courier/except.h> 


AdditemPropertyResults 
AdditemProperty( Connection, BDTprocptr, name, newProperty, value, agent) 
COURIERFD Connection; ~~ 
int(* BDTprocptr)(); 
ThreePartName name; 
LongCardinal newProperty; 
Item value; 
Authenticator agent; 


DESCRIPTION 


The AdditemProperty function is used to add a property of a specified value to an object. The property 
value will be of type Item. Item type properties are not inspected by the Clearinghouse and therefore do 
not have to adhere to Clearinghouse rules. An object may have up to 250 properties associated with it. 


A Clearinghouse object is comprised of three parts: a property number (ID), a property type, and a value. 
A property is primarily used to hold a network location, or a list of other object names. Given an object 
name and a property number, the Clearinghouse will return the value of that property, which will be 
either a block of data (if the property type is item), or a list of names (if the property type is group). The 
Clearinghouse does not inspect item properties, therefore they may consist of any data the client wishes. 
The group property, on the other hand, is inspected and recognized by the Clearinghouse, therefore each 
group property must contain a sequence of Clearinghouse names called members.The name argument is 
the Clearinghouse name of the object. The name may be either the actual name of an object or an alias. 
UNIX wildcards may not be used in specifying any part of the object name. 


If an attempt is made to add a property that already exists, even if it has a different value, the attempt will 
be ignored. Use Changeltem() to change the value of an existing item property. 


The name argument is the name of the object to which the property will be added. It may be either the 
actual name of the object or an alias. UNIX wildcards may not be used to specify any portion of the name 
argument. The newProperty argument is an integer that identifies the property to be added. The value 
property is the initial value, or data, to be assigned the new property. 


The agent argument is a structure whose two members contain the client’s credentials and verifier. 


RETURN VALUE 
This function returns a structure called AdditemPropertyResults. Its one member, distinguishedObject, is 
of type ThreePartName. It is the full name of the object to which the item type property was added. 
ERRORS 


Reports [ArgumentError[problem], AuthenticationError[problem], CallError[problem], 
PropertyError[problem], UpdateError[problem], WrongServer] 
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SEE ALSO 
AddGroupProperty(), ListProperties() 
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Clearinghouse2__AddMember, _ AddSelf 


NAME 


AddMember - add a member to a group type property 
AddSelf - add the user to a group type property 


SYNOPSIS 


#include <courier/Clearing2 _de.h> 
#include <courier/except.h> 


AddMemberResults 
AddMember( Connection, BDTprocptr, name, property, newMember, agent) 
COURIERFD Connection; 
int(* BDTprocptr)(); 
ThreePartName name; 
LongCardinal property; 
ThreePartName newMember; 
Authenticator agent; 


AddSelfResults 
AddSelf( Connection, BDTprocptr, name, property, agent) 
COURIERFD Connection; 
int(* BDTprocptr)(); 
ThreePartName name; 
LongCardinal property; 
Authenticator agent; 


DESCRIPTION 


The AddMember() function is used to add a new member to a group type property of an object. The 
AddSelif() function is used to add the user identified by the agent argument to a group property of an 
object. 


The value of a group property is understood by the Clearinghouse to be a sequence of Clearinghouse 
names called members. The new member may be a distinguished name, an alias, or the name of a 
Clearinghouse object that does not currently exist. The name of the member does not have to be registered 
with the Clearinghouse at the time of calling this function, though the object must be registered. 


The name argument specifies the object to which the new member is to be added. It is of type 
ThreePartName. Its members, organization, domain, and object, identify the object in question. UNIX 
wildcards may not be used to specify any part of the name. If the object name encountered is an alias, it is 
dereferenced before it is processed. 


The property argument specifies the property number of the property to which the new member will be 
added. The newMember argument identifies the new member. It is specified as being of type 
ThreePartName. 


The agent argument is a structure of type Authenticator. Its two members contain the client’s credentials 
and verifier. In the case of AddSelf, agent identifies the user and verifies the user’s credentials. In the 
case of AddMember, it simply verifies the user’s credentials. The new user is identified by the 
newMember argument. 
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RETURN VALUE 


AddMember() and AddSelf() return structures called AddMemberResults and AddSelfResults, 
respectively. They both have one member, distinguishedObject, which is of type ThreePartName. It is the 
distinguished name of the object to whose group type property the member was added. 


ERRORS 


Reports [ArgumentError[problem], AuthenticationError[problem], CallError[problem], 
PropertyError[problem], UpdateError[problem], WrongServer] 


SEE ALSO 
DeleteMember(), AddGroupProperty() 
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Clearinghouse2__Changeltem 


NAME 
Changeltem - modify the value of an item type property 


SYNOPSIS 


#include <courier/Clearing2 de.h> 
#include <courier/except.h>_ 


ChangeltemResults 
Changeltem( Connection, BDTprocptr,name, property, newValue, agent) 
COURIERFD Connection; 
int(* BDTprocptr)(); 
ThreePartName name; 
LongCardinal property; 
Item newValue; 
Authenticator agent; 


DESCRIPTION 


The Changeltem() function is used to assign a new value to an item type property. The name argument is 
comprised of three strings that identify the organization, domain, and name of an object. Wildcards may 
not be used to specify any portion of this argument. The property argument identifies the item type 
property for which a new value is to be assigned. The newValue argument is the intended new value of the 
property. The agent argument is a structure whose two members contain the client’s credentials and 
verifier. 

RETURN VALUE 
This function returns a structure called ChangeltemResults. Its one member, distinguishedObject, is of 
type ThreePartName. It is the full path name of the object whose item type property was modified. 

ERRORS 
Reports [ArgumentError[problem], AuthenticationError[problem], CallError[problem], 
PropertyError[problem], UpdateError[problem], WrongServer] 

SEE ALSO 


AdditemProperty(), Retrieveltem(), ListProperties(), IsMember() 
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Clearinghouse2__CreateAlias, DeleteAlias, _ListAliases 


NAME 


CreateAlias - add an alias to an object 
DeleteAlias - delete an alias of an object 
ListAliases - list objects that are aliases 


SYNOPSIS 


#include <courier/Clearing2_de.h> 
#include <courier/except.h> 


CreateAliasResults 
CreateAlias( Connection, BDTprocptr, alias, sameAs, agent) 
COURIERFD Connection; 
int(* BDTprocptr)(); 
ThreePartName alias; 
ThreePartName sameAs; 
Authenticator agent; 


DeleteAliasResults 
DeleteAlias( Connection, BDTprocptr, alias, agent) 
COURIERFD Connection; 
int(* BDTprocptr)(); 
ThreePartName alias; 
Authenticator agent; 


void 
ListAliases( Connection, BDTprocptr, pattern, list, agent) 
COURIERFD Connection; 
int(* BDTprocptr)(); 
ThreePartName pattern; 
BulkData1 Descriptor list; 
Authenticator agent; 


DESCRIPTION 


The CreateAlias() function is used to add a new alias to an object in the Clearinghouse database. If the 
object being aliased is itself an alias, the existing alias will be dereferenced before proceeding. The 
resulting alias will point to the actual object rather than the alias of the object. Cross-domain aliases are 
allowed. 


The DeleteAlias() function is used to remove an alias of an object in the Clearinghouse database. 


The ListAliases() function is used to list the objects in a specific domain which are aliases and match 
pattern. 


The alias argument is the name by which the object may be referenced. In the case of CreateAlias(), the 
alias argument is the name of the new alias to be attributed to the object. Wildcard characters may not be 


used. 


The sameAs argument is the actual name, or existing alias, of the object to which the new alias will point. 
No wildcards may be used in specifying the sameAs argument. 
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The value of the pattern argument is a structure whose members specifies the organization, domain, and 
object name of the object whose aliases are to be listed. Wildcards may be used in specifying the object, but 
not the domain and organization. The search for an object stops upon the first occurrence of a match. 


The value of the list argument specifies the sink that is to receive the list of aliases, in accordance to the 
Bulk Data Transfer Protocol. The list of aliases placed in the sink will be of type SegmentOfObject. 


The agent argument is a structure whose two members contain the client’s credentials and verifier. 


RETURN VALUE 


CreateAlias() returns a structure called CreateAliasResults. Its one member, distinguishedObject, is of 
type ThreePartName. It is the full name of the object to which the aliases point. DeleteAlias() returns a 
structure called DeleteAliasResults. Its one member, distinguishedObject, is of type ThreePartName. It is 
the full name of the object to which the aliases pointed. ListAliases() returns void. 


ERRORS 


CreateAlias() and DeleteAlias() both report [ArgumentError[problem], AuthenticationError[problem], 
CallError[problem], UpdateError[problem], WrongServer]. ListAliases() reports 
[ArgumentError[problem], AuthenticationError[problem], CallError[problem], WrongServer] 
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Clearinghouse2__ CreateObject 


NAME 

CreateObject - create a Clearinghouse object 
SYNOPSIS 

#include <courier/Clearing2 de.h> 


#include <courier/except.h>~ 


void 
CreateObject(_ Connection, BDTprocptr, name, agent) 
COURIERFD _ Connection; 
int (*_ B DTprocptr)(); 
ThreePartName name; 
Authenticator agent; 
DESCRIPTION 
The CreateObject() function is used to create a new distinguished object in the Clearinghouse database. 
Distinguished means the object is not aliased. 


The name argument is a string that specifies the object’s name, domain, and organization. It may not 
contain wildcards. 


The value of the agent argument is a structure whose two members contain the client’s credentials and 
verifier, as defined in the Authentication protocol. 


RETURN VALUE 


This function returns void. 


ERRORS 


Reports [ArgumentError[problem], AuthenticationError[problem], CallError[problem], 
UpdateError[problem], WrongServer] 


SEE ALSO 
CheckSimpleCredentials() 
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Clearinghouse2__DeleteMember, _ DeleteSelf 


NAME 


DeleteMember - remove a member of a group type property 
DeleteSelf - remove a user from a group type property 


SYNOPSIS 


#include <courier/Clearing2 _de.h> 
#include <courier/except.h> 


DeleteMemberResults 
DeleteMember( Connection, BDTprocptr, name, property, member, agent) 
COURIERFD Connection; — 
int(* BDTprocptr)(); 
ThreePartName name; 
LongCardinal property; 
ThreePartName member; 
Authenticator agent; 


DeleteSelfResults 
DeleteSelf( Connection, BDTprocptr, name, property, agent) 
COURIERFD Connection; 
int(* BDTprocptr)(); 
ThreePartName name; 
LongCardinal property; 
Authenticator agent; 


DESCRIPTION 


The DeleteMember() function is used to delete a member from a group type property of an object. The 
DeleteSelf() function deletes the user identified by the agent argument from a group type property of an 
object. 


The name argument specifies the object from which the member or user is to be deleted. It is of type 
ThreePartName. Its three members, organization, domain, and object, identify the object in question. 
UNIX wildcards may not be used to specify any part of the name. If the object name encountered is an 
alias, it is dereferenced before it is processed. 


The property argument indicates the group type property from which the specified member or user will be 
deleted. 


In the case of DeleteMember(), the member argument is the name of the member that is to be deleted from 
the Clearinghouse database. Like the name argument, it is of type ThreePartName. UNIX wildcards may 
not be used to specify any part of the member. However, members of type group may be specified patterns, 
in which case, wildcards may be included in the name string and will be interpreted literally. Since the 
specified member is not verified by the Clearinghouse, any properly formed member name may be 
specified. 


The agent argument is a structure whose two members contain the client’s credentials and verifier. 


DOCUMENT INTERFACES TOOLKIT SYSTEM REFERENCE 8-23 


XNS LIBRARY 


RETURN VALUE 
DeleteMember() and DeleteSelf() returns structures called DeleteMemberResults and DeleteSelfResults, 
respectively. They both contain one member, distinguishedObject. It is of type ThreePartName. It is the 
full path name of the object from whose group type property the member was removed. 

ERRORS 
Reports [ArgumentError[problem], AuthenticationError[problem], CallError[problem], 
PropertyError[problem], UpdateError[problem], WrongServer] 

SEE ALSO 
AddMember(), AddSelf() 
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Clearinghouse2__DeleteObject 


NAME 
DeleteObject — delete a Clearinghouse object 


SYNOPSIS 
#include <courier/Clearing2_de.h> 
#include <courier/except.h> 


void 
DeleteObject(_ Connection, _BDTprocptr, name, agent) 
COURIERFD Connection; 
int(* _BDTprocptr)(); 
ThreePartName name; 
Authenticator agent; 
DESCRIPTION 
The DeleteObject() function is used to delete an object from the Clearinghouse database. 
The name argument is of type ThreePartName, a string that specifies the object’s name, domain and 


organization. If the name argument is an alias, it is first dereferenced. As a result, all aliases that point to 
the specified object will also be deleted. name may not contain any wildcard characters. 


The value of the agent argument is a structure whose members contain the client’s credentials and 
verifier. 


RETURN VALUE 


This function returns void. 


ERRORS 


Reports [ArgumentError[problem], AuthenticationError[problem], CallError[problem], 
UpdateError[problem], WrongServer] 
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Clearinghouse2__DeleteProperty 


NAME 


DeleteProperty -- remove an object property 


SYNOPSIS 
#include <courier/Clearing2 de.h> 
#include <courier/except.h> 


DeletePropertyResults 
DeleteProperty( Connection, BDTprocptr, name, property, agent) 
COURIERFD Connection; _ 
int(* BDTprocptr)(); 
ThreePartName name; 
LongCardinal property; 
Authenticator agent; 


DESCRIPTION 


The DeleteProperty() function is used to remove a specific property from an object. Both the property 
number and its value are deleted. The property number may then be used again when adding new 
properties to the object. Note that an object is not automatically removed when its last property has been 
deleted. 


The name argument is the complete Clearinghouse name of an object from which a property is to be 
removed. Wildcard characters may not be used to specify any portion of this argument. Aliases may be 
used. 


The property argument is an integer that identifies the property to be deleted. 
The agent argument is a structure whose two members contain the client’s credentials and verifier. 


RETURN VALUE 


This function returns a structure called DeletePropertyResults. Its one member, distinguishedObject, is of 
type ThreePartName. It is the path name of the object from which the specified property was removed. 


ERRORS 


Reports [ArgumentError[problem], AuthenticationError[problem], CallError[problem], 
PropertyError[problem], UpdateError[problem], WrongServer] 


SEE ALSO 
AdditemProperty(), AddGroupProperty(), ListProperties() 
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Clearinghouse2__IsMember 


NAME 


IsMember - determine membership of an object 


SYNOPSIS 


#include <courier/Clearing2 de.h> 
#include <courier/except.h> 


IsMemberResults 
IsMember( Connection, BDTprocptr, memberOf, property, secondaryProperty, name, agent) 
COURIERFD Connection; 
int(* BDTprocptr)(); 
ThreePartName memberOf; 
LongCardinal property; 
LongCardinal secondaryProperty; 
ThreePartName name; 
Authenticator agent; 


DESCRIPTION 


The IsMember() function determines if a named object is a member of a group type property. IsMember() 
has two modes of operation which are determined by the secondaryProperty argument: normal and group. 
The normal mode examines only the members of a specified property. The group mode extends the search 
to include the membership of groups listed within the initial group property. 


In normal mode, the specified member object is compared against every object belonging to a specific group 
type property. This process continues until the first occurrence of a match. 


A database object may have numerous group or item properties associated with it. A group property 
contains objects which may, in turn, also contain group properties. In group mode operation, the search 
algorithm is such that the first group property entry encountered is examined to determine if it is an 
object. If it is not an object, the search algorithm continues to the next entry of the group property. If the 
group property entry is an object, the algorithm compares the object name against the name specified in 
the memberOf argument. If it does match, the search stops and the database object name is returned. If it 
does not match, the group property entry is examined further to determine if it may, in turn, contain 
objects having group properties. If a lower level object has a group property, the name of each object in the 
lower level group property is compared against the name specified in the memberOf argument. If there is 
more than one lower level group property, the algorithm searches each lower level group property for an 
object name that matches the one specified in the memberOf argument. This applies only when the group 
properties have a PID = secondaryProperty. If there are no matches, the algorithm pops back up a level to 
the original group property. This search algorithm is performed on every object within the original group 
property, including all sub-levels, until a match is found. 


The memberOf argument is of type ThreePartName. It three members, organization, domain, and object, 
identify the group property to be examined. UNIX wildcards may be used in both the normal and group 
modes to specify any part of the name argument. However, wildcards will only be interpreted as such in 
the object name field. Wildcards used in the domain and organization fields will be interpreted as normal 
characters, devoid of any wildcard significance. 


The property argument is an integer that identifies the group property to be searched. 
The secondaryProperty argument controls the mode of operation. A value of nullProperty, 37777777777B, 


indicates that only the members of property are examined for name. If any other property ID number is 


DOCUMENT INTERFACES TOOLKIT SYSTEM REFERENCE 8-27 


XNS LIBRARY 


entered as the value of secondaryProperty, then the group property having the specified ID number is also 
searched for the named object. 


The name argument is of type ThreePartName. Its three members, organization, domain, and object, 
identify the object for whom membership is being determined. UNIX wildcards may be used but are 
interpreted literally. name may be an alias. It is not de-referenced before testing for membership. 


The agent argument is a structure whose two members contain the client’s credentials and verifier. 


RETURN VALUE 
This function returns a structure called IsMemberResults. It has two members: isMember and 
distinguishedObject. IsMember is a Boolean whose value indicates if the named object had been found 
(TRUE) or not (FALSE). distinguishedObject is the full path name of the object specified in the memberOf 
argument. It is of type ThreePartName. 

ERRORS 
Reports [ArgumentError[problem], AuthenticationError[problem], CallError[problem], 
PropertyError[problem], WrongServer] 

SEE ALSO 


AddMember(), AddSelf() 
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Clearinghouse2__ListAliasesOf 


NAME 
ListAliasesOf - list the aliases of an object 


SYNOPSIS 
#include <courier/Clearing2 de.h> 
#include <courier/except.h> 


ListAliasesOfResults 
ListAliasesOf( Connection, BDTprocptr, pattern, list, agent) 
COURIERFD Connection; 
int(* BDTprocptr)(); 
ThreePartName pattern; 
BulkData1 Descriptor list; 
Authenticator agent; 


DESCRIPTION 


The ListAliasesOf() function is used to list the aliases of an object. 


The pattern argument is of type ThreePartName, a structure whose members specify the desired 
Organization, domain, and object name. UNIX wildcards may be used to specify the object, but not the 
domain and organization. The search for an object using wildcards stops upon the first occurrence of a 
match. If the object name encountered is an alias, it is dereferenced before its aliases are determined. 


The list argument specifies the sink that is to receive the aliases of an object, in accordance to the Bulk 
Data Transfer Protocol. The list of aliases placed in the sink will be of type SegmentOfObjectName. 


The agent argument is a structure whose two members contain the client’s credentials and verifier. 


RETURN VALUE 


This function returns a structure called ListAliasesOfResults. Its one member, BisunguisnecOBiect is of 
type ThreePartName. It is the full name of the object to which the aliases point. 


ERRORS 
Reports [ArgumentError[problem], AuthenticationError[problem], CallError[problem], WrongServer] 
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Clearinghouse2__ListDomain 


NAME 


ListDomain - list the domains in an organization 


SYNOPSIS 
#include <courier/Clearing2 _de.h> 
#include <courier/except.h> 


void 
ListDomain( Connection, BDTprocptr, pattern, list, agent) 
COURIERFD Connection; 
int(* BDTprocptr)(); 
ThreePartName pattern; 
BulkData1 Descriptor list; 
Authenticator agent; 


DESCRIPTION 


The ListDomain() function is used to list domain names within an organization. 


The pattern argument is a text string that specifies the target organization and domain(s). UNIX 
wildcards may be used to specify the domain, but not the organization. The search continues through the 
entire Clearinghouse database, returning all the domain names that match the specified pattern. The list 
argument specifies the sink that is to receive the list of organizations, in accordance to the Bulk Data 
Transfer Protocol. The list of domains placed in the sink will be of type SegmentOfDomain. 


The agent argument is a structure whose two members contain the client’s credentials and verifier. 


RETURN VALUE 


This function returns void. 


ERRORS 


Reports [ArgumentError[problem], AuthenticationError[problem], CallError[problem], WrongServer] 
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Clearinghouse2__ListDomainServed 


NAME 


ListDomainServed - determine the domains served by a Clearinghouse 


SYNOPSIS 
#include <courier/Clearing2 de.h> 
#include <courier/except.h> 


void 
ListDomainServed( Connection, BDTprocptr, domains, agent) 
COURIERFD Connection; ~— 
int(* BDTprocptr)(); 
BulkData1 Descriptor domains; 
Authenticator agent; 
DESCRIPTION 
The ListDomainServed() function is used to obtain a list of the domains served by a specific Clearinghouse 
service. 


The domains argument is a bulk data transfer parameter that specifies the sink that is to receive the list 
of domains in accordance with the Bulk Data Transfer Protocol. The data returned to the sink is of type 
SegmentOfDomainName. 


The agent argument is a structure whose two members contain the client’s credentials and verifier. 


RETURN VALUE 


This function returns void. 


ERRORS 
Reports AuthenticationError[problem], CallError[problem]] 
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Clearinghouse2__ListObjects 


NAME 


ListObjects - list objects in a domain 


SYNOPSIS 


#include <courier/Clearing2__de.h> 
#include <courier/except.h> 


void 
ListObjects( Connection, BDTprocptr, pattern, property, list, agent) 
COURIERFD Connection; 
int(* BDTprocptr)(); 
ThreePartName pattern; 
LongCardinal property; 
BulkData1 Descriptor list; 
Authenticator agent; 


DESCRIPTION 
The ListObjects() function is used to list the objects in a domain that have a specific property associated 
with them. 


The pattern argument is of type ThreePartName, a structure whose members specify the desired 
Organization, domain, and object names. UNIX wildcards may be used to specify the object, but not the 
domain and organization. The property argument is used to specify a property that each object matching 
the search pattern must have in order for it to be listed. One property number of particular importance is 
0. 0 is synonymous with all. When 0 is specified, it indicates that all the objects in a domain that match the 
pattern, regardless of intrinsic properties, are to be listed. 


The list argument specifies the sink that is to receive the list of domains, in accordance to the Bulk Data 
Transfer Protocol. The list of organizations placed in the sink will be of type SegmentOfObject. 


The agent argument is a structure whose two members contain the client’s credentials and verifier. 


RETURN VALUE 


This function returns void. 


ERRORS 


Reports [ArgumentError[problem], AuthenticationError[problem], CallError[problem], WrongServer] 
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Clearinghouse2__ListOrganizations 


NAME 


ListOrganizations — list Clearinghouse organizations 


SYNOPSIS 


#include <courier/Clearing2_de.h> 
#include <courier/except.h> 


void 
ListOrganizations( Connection, BDTprocptr, pattern, list, agent) 
COURIERFD Connection; ~~ 
int(* BDTprocptr)(); 
String pattern; 
BulkData1 Descriptor list; 
Authenticator agent; 


DESCRIPTION 


The ListOrganizations() function is used to list the names of organizations in the Clearinghouse database. 


The pattern argument is a string that specifies the set of organizations to be listed. pattern is typically the 
partial spelling of the desired Clearinghouse organization names . Wildcard characters may be included in 
the partial spelling. The search continues through the entire Clearinghouse database, returning all 
organization names that match the specified pattern. The list argument specifies the sink that is to receive 
the list of organizations, in accordance to the Bulk Data Transfer Protocol. The list of organizations placed 
in the sink will be of type SegmentOfOrganization. 


The agent argument is a structure whose two members contain the client’s credentials and verifier. 


~ RETURN VALUE 


This function returns void. 


ERRORS 


Reports [ArgumentError[problem], AuthenticationError[problem], CallError[problem], WrongServer] 
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Clearinghouse2__ListProperties 


NAME 


ListProperties -- list the property numbers of an object 


SYNOPSIS 


#include <courier/Clearing2__de.h> 
#include <courier/except.h> 


ListPropertiesResults 
ListProperties( Connection, BDTprocptr, pattern, agent) 
COURIERFD Connection; 
int(* BDTprocptr)(); 
ThreePartName pattern; 
Authenticator agent; 


DESCRIPTION 


The ListProperties() function is used to list the ID number of every property associated with an object. The 
pattern argument is of type ThreePartName. It is a structure whose members specify the organization, 
domain, and object name of the object whose property numbers are to be listed. UNIX wildcards may be 
used in specifying the object, but not the domain or organization. The search for an object using wildcards 
stops upon the first occurrence of a match. 


The agent argument is a structure whose two members contain the client’s credentials and verifier. 


RETURN VALUE 


This function returns a structure called ListPropertiesResults. Its has two members: distinguishedObject 
and properties. distinguishedObject is of type ThreePartName. It is the full name of the object in question. 
properties is of type Properties. properties is a list of the properties associated with the object. Note that 
properties are referred to by number, not name. 


ERRORS 


Reports [ArgumentError[problem], AuthenticationError[problem], CallError[problem], WrongServer] 


SEE ALSO 
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AdditemProperty(), AddGroupProperty() 
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Clearinghouse2__LookupObject 


NAME 


LookupObject — retrieve an object name 


SYNOPSIS 


#include <courier/Clearing2__de.h> 
#include <courier/except.h> 


LookupObjectResults 
LookupObject( Connection, BDTprocptr, name, agent) 
COURIERFD Connection; _ 
int(* BDTprocptr)(); 
ThreePartName name; 
Authenticator agent; 


DESCRIPTION 
The LookupObject() function is used to query the Clearinghouse database for the full name of an object 
that is contained within it. 


The name argument is the name of the object in the Clearinghouse. The name that is specified may be a 
partial spelling, an alias, or both. Wildcard characters may be included in the partial spelling of the 
object name, but not the domain and organization. The search continues until the first occurrence of the 
named object, or its alias, is encountered. If the object’s alias is encountered, it is dereferenced before being 
returned to the calling function. 


The value of the agent argument is a structure whose members contain the client’s credentials and 
verifier. 


RETURN VALUE 


This function returns a structure called LookupObjectResults. Its one member, distinguishedObject, is of 
type ThreePartName. It is the complete name of the Clearinghouse database object in question. 


ERRORS 
Reports [ArgumentError[problem], AuthenticationError[problem], CallError[problem], WrongServer] 
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Clearinghouse2__RetrieveAddresses 


NAME 


RetrieveAddresses - query a Server for its network addresses 


SYNOPSIS 


#include <courier/Clearing2 de.h> 
#include <courier/except.h> 


RetrieveAddressesResults 

RetrieveAddresses( Connection, BDTprocptr) 
COURIERFD Connection; ~~ 
int (* _BDTprocptr)(); 


DESCRIPTION 


The RetrieveAddresses() function is used to query the clearinghouse server for a list of all of its network 
addresses. This function knows the Clearinghouse server to access based upon the value of the 

Connection argument. This function may also be used as a check to insure the Clearinghouse server is 
available before calling other functions. 


RETURN VALUE 


This function returns a structure called RetrieveAddressesResults. Its one member, address, is of type 
NetworkAddressList. It contains a list of the network addresses recognized by the Clearinghouse. A 
network address entry is defined in Xerox Network Systems Architecture as host number (48b:1), network 
number (32 bit integer), and a socket number (16 bit integer). The maximum number of entries returned is 
40. 


ERRORS 
Reports [CallError[problem]] 
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Clearinghouse2__ Retrieveltem 


NAME 


Retrieveltem - list the value of an item type property 


SYNOPSIS 


#include <courier/Clearing2 de.h> 
#include <courier/except.h > 


RetrieveltemResults 
Retrieveltem( Connection, BDTprocptr, pattern, property, agent) 
COURIERFD Connection; 
int(* BDTprocptr\(); 
ThreePartName pattern; 
LongCardinal property; 
Authenticator agent; 


DESCRIPTION 
The Retrieveltem() function is used to determine the value of an item type property that is associated with 
an object. This function returns both the distinguished object name, and the value of the item property. 


The pattern argument is of type ThreePartName, a structure whose members specify the organization, 
domain, and object name of the object from which the value of property is to be extracted. UNIX wildcards 
may be used in specifying the object, but not the domain and organization. The search for an object using 
wildcards stops upon the first occurrence of a match. If the object name encountered is an alias, it is 
dereferenced before it is returned. 


The property argument specifies the ID number of the property for which its value is to be returned. UNIX 
wildcards may not be used. 


Properties are referred to by ID number, not name. One property number of particular importance is 0. 0 is 
synonymous with all. When 0 is specified, it indicates that all the item properties of the first object 
encountered that matches the specified pattern are to be returned. 


The agent argument is a structure whose two members contain the client’s credentials and verifier. 


RETURN VALUE 


This function returns a structure called RetrieveltemResults. It has two members: distinguishedObject 
and value. distinguishedObject is of type ThreePartName. It is the full name of the object whose item type 
property is being listed. value is of type Item. It contains the value of the item property. 


ERRORS 


Reports [ArgumentError[problem], AuthenticationError[problem], CallError[problem], 
PropertyError[problem], WrongServer] 


SEE ALSO 
AdditemProperty(), AddGroupProperty(), ListProperties(), IsMember() 
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Clearinghouse2__RetrieveMembers 


NAME 


RetrieveMembers - retrieve the value of a group type property 


SYNOPSIS 


#include <courier/Clearing2__de.h> 
#include <courier/except.h> 


RetrieveMembersResults 
RetrieveMembers( Connection, BDTprocptr, pattern, property, membership, agent) 
COURIERFD Connection; 
int(* BDTprocptr)(); 
ThreePartName pattern; 
LongCardinal property; 
BulkData1 Descriptor membership; 
Authenticator agent; 


DESCRIPTION 


The RetrieveMembers() function is used to extract, or retrieve, the value of a group type property 
associated with an object. The pattern argument is of type ThreePartName. It is a structure whose 
members, organization, domain, and object, identify the object in question. UNIX wildcards may be used 
to specify the object, but not the domain and organization. The search for an object using wildcards stops 
upon the first occurrence of a match. If the object name encountered is an alias, it is dereferenced. 


The property argument identifies the property from which a value is to be retrieved. One property number 
of particular importance is 0. 0 is synonymous with all. When 0 is specified, it indicates that all the group 
properties that match the criteria specified in pattern are to be returned. 


The membership argument is a bulk data parameter that specifies the sink that is to receive the list of 
values in accordance to the Bulk Data Transfer Protocol. The data received via the membership argument 


is of the type StreamOfThreePartName. 


The agent argument is a structure whose two members contain the client’s credentials and verifier. 


RETURN VALUE 


This function returns a structure called RetrieveMembersResults. Its one member, distinguishedObject, is 
of type ThreePartName. It is the full name of the object from which the property value was extracted. 


ERRORS 


Reports [ArgumentError[problem], AuthenticationError[problem], CallError[problem], 
PropertyError[problem], WrongServer] 


SEE ALSO 


Retrieveltem(), IsMember() 
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Filing6__Close 


NAME 


Close - terminate a file handle 


SYNOPSIS 


#include <courier/Filing6 de.h> 
#include <courier/except.h> 


void 
Close( Connection, BDTprocptr, file, session) 
COURIERFD Connection; 
int(* BDTprocptr)(); 
Handle file; 
Session session; 
DESCRIPTION 


The Close() function is used to indicate to the File Service that a specific file handle is no longer wanted for 
the remainder of the current session. The File Service then releases acquired resources, such as locks 
associated with the handle, and invalidates the file handle. If no other file handle is associated with it, the 
file buffer is also purged. 


The file argument is the file handle originally returned by a call to the Open() function. It specifies the file 
that is to be closed. The session argument is the client's session handle that was returned upon executing 
the Logon() function. 


RETURN VALUE 


This function returns void. 


ERRORS 


Reports [AuthenticationError[problem], HandleError, SessionError[problem], UndefinedError] 


SEE ALSO 
Open(), Logon() 
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Filing6__ Continue 


NAME 


Continue - lengthen the duration of an inactive session 


SYNOPSIS 


#include <courier/Filing6 de.h> 
#include <courier/except-h> 


ContinueResults 

Continue( Connection, BDTprocptr, session) 
COURIERFD Connection; 
int(* BDTprocptr)(); 
Session session; 


DESCRIPTION 


The Continue() function is used to determine the duration, in seconds, permitted an inactive session before 
it is terminated by the File Service. The duration of inactivity permitted a session is determined by the 
File Service. A call to Continue(), as with all other remote function calls, is considered activity and 
therefore, the session is reallocated the full amount of time permitted an inactive session. The session 
argument is the session handle returned by an call to Logon(). It is the session to be lengthened. 


RETURN VALUE 


This function returns a structure called ContinueResults. Its one member, continuance, is a cardinal 
number that specifies the timeout period of the file server. The timeout is specified in units of seconds. The 
returned value indicates the frequency with which the client must perform some activity. For example, to 
determine the timeout period of a session, use Continue(): 


Continue(token, (11B,27734B), verifier) 
It returns: 
(600) 


Therefore, to prevent termination of the current session some activity must occur within every ten 
minutes (600 seconds). 


ERRORS 


Reports [AuthenticationError[problem], SessionError[problem], UndefinedError] 


SEE ALSO 
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Logon() 
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Filing6__Copy 


NAME 
Copy - create a duplicate file 


SYNOPSIS 


#include <courier/Filing6é de.h> 
#include <courier/except.h> 


CopyResults 
Copy( Connection, BDTprocptr, file, destinationDirectory, attributes, controls, session) 
COURIERFD Connection; 
int(* BDTprocptr)(); 
Handle file; 
Handle destinationDirectory; 
AttributeSequence attributes; 
ControlSequence controls; 
Session session; 


DESCRIPTION 


The Copy() function is used to duplicate an existing file or directory. If the object to be copied is a directory, 
all the descendants are also copied. The duplicate file or directory is then placed into a specified directory. 
A file or directory cannot be copied into itself or any of its descendants. 


The file argument is the file handle of the file or directory to be copied. Read access (i.e., read permission) 
is required of the file. If the object is a directory, then read access is required of all its descendants. 


The destinationDirectory argument is the file handle for the directory in which the copy is to be placed. 
Add access (i.e.,write permission) is required of the destination directory. The value of 
destinationDirectory may be set to nullHandle, thus indicating that the resulting file is to be placed in the 
root directory. 


The attributes argument specifies the sequence of characteristics to be assigned to the new file or 
directory, thus overriding those of the original file or directory. 


The controls argument specifies the access permissions of the new file or directory. 


The session argument is the client's session handle that was returned upon executing the Logon() 
function. 


RETURN VALUE 


This function returns a structure called CopyResults. Its one member, newFile, is of type Handle. It isa 
handle for the newly created file or directory. 


ERRORS 


Reports [AccessError[problem], AuthenticationError[problem], HandleError, SessionError[problem], 
UndefinedError] 
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Filing6__Create | 


NAME 


Create - make a new file 


SYNOPSIS 


#include <courier/Filing6é de.h> 
#include <courier/except.h> 


CreateResults 
Create( Connection, BDTprocptr, directory, attributes, controls, session) 


COURIERFD Connection; 
int(* BDTprocptr)(); 

Handle directory; 
AttributesSequence attributes; 
ControlSequence controls; 
Session session; 


DESCRIPTION 


The Create() function is used to make a new file. Create() is particularly useful for creating directories. If 
the file to be created is also to contain some data, use the Store() function. 


The directory argument is the file handle for the directory in which the created file will be placed. 


null 


Handle may be specified, indicating that the file will be placed in the root level directory. 


attributes are data items associated with a file. See Open() for a description of attributes. 


controls define the nature of permissible file access that a file handle gives to the client. controls may be 
specified in any function that returns a file handle. The controls specified apply only to the returned 
handle. controls is a structure that contains three enumerated types: LOCK, TIMEOUT, and ACCESS. 


LOCK offers three choices: NONE, SHARE, and EXCLUSIVE. NONE indicates that there are no access 
restrictions. SHARE means that other sessions cannot move or delete the file, and cannot place an 
exclusive lock on the file. EXCLUSIVE means that other sessions cannot move or delete the file, and 
cannot place a SHARE or EXCLUSIVE lock on the file. 


TIMEOUT is an integer that indicates the number of seconds that the File Service will wait after a 
client requests a lock on a file that is unavailable. If the time specified is exceeded and the locked file 
does not become available, an error is returned. The interval that the File Service will wait is usually 
an implementation-dependent constant, though you may specify an overriding interval. If a TIMEOUT 
of zero is specified, the File Service will not wait. If the locked file is unavailable, an error is 
immediately returned. If 177777B (defaultTimeout) is specified, the implementation-dependent 
default is applied. If no TIMEOUT is specified, defaultTimeout is assumed. 


ACCESS specifies the operations permitted a particular file handle with respect to a file or its children. 
If access permissions have not been enabled, the file handle may not be used in any operation that 
attempts to access the specific file. The six acceptable values of access are: READ, WRITE, OWNER, 
ADD, REMOVE, and FULLACCESS(177777B). 


READ means the client may read the contents and attributes of a file. If it is a directory, the client 
may enumerate its children and search for files in that directory. WRITE permits the client to 
modify the contents and attributes of the file. This includes deleting the file. If it is a directory, a 
client may also change environment attributes access lists of the directory's children. OWNER 
means a client may change the file's access list. ADD permits a client to add subdirectories and 
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files. REMOVE may only be applied to directories. It allows a client to delete subdirectories. 
FULLACCESS(177777B) means a client is granted the complete set of access permissions. That is, 


read, write, change the access list (owner), add, and remove. FULLACCESS cannot be specified along 
with any of the preceding access types. 


The session argument is the client's session handle that was returned upon executing the Logon() 
function. 


RETURN VALUE 


This function returns a structure called CreateResults. Its one member, file, is of type Handle. It contains 
the file handle for the newly created file. 


ERRORS 


Reports [AccessError[problem], AttributeTypeError, AttributeValueError, 
AuthenticationError[problem], ControlTypeError, Control ValueError, HandleError, InsertionError, 
SessionError[problem], SpaceError, UndefinedError] 
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Filing6__Delete 


NAME 


Delete - remove an existing file 


SYNOPSIS 


#include <courier/Filing6 de.h> 
#include <courier/excepth> 


void 
Delete( Connection, BDTprocptr, file, session) 
COUORIERFD Connection; 
int(* BDTprocptr)(); 
Handle file; 
Session session; 


DESCRIPTION 


The Delete() function is used to remove an existing file. When this function is called, the target file is 
closed and then deleted. All resources allocated to the file are then freed for other uses. Once the file is 
deleted, the file handle associated with it becomes invalid. 


The file argument is the file handle of the file to be deleted. The file to be deleted can have only one file 
handle during the current session. If the file handle specifies a directory, the directory and all its 
descendents will be deleted. 


The session argument is the client's session handle that was returned upon executing the Logon() 
function. 


RETURN VALUE 


This function returns void. 


ERRORS 


Reports [AccessError[problem], AuthenticationError[problem], HandleError, SessionError[problem], 
UndefinedError] 


SEE ALSO 
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Logon() 
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Filing6__Find 


NAME 


Find - locate a file 


SYNOPSIS 


#include <courier/Filing6é de.h> 
#include <courier/except.h> 


FindResults 
Find( Connection, BDTprocptr, directory, scope, controls, session) 
COURIERFD Connection; 
int(* BDTprocptr)(); 
Handle directory; 
ScopeSequence scope 
ControlSequence controls; 
Session session; 


DESCRIPTION 


The Find() function is used to locate and open a file in a directory. The File Service enumerates the 
directory's descendants in accordance to the ordering attribute of the directory. The first file that meets 
the search criteria is opened. If no file matches the search criteria, an error is reported. 


The directory argument is the file handle of the directory whose descendants are to be enumerated. 
nullHandle may be specified to indicate that the search is to begin at the root directory. Read access (i.e., 
read permission) is required of the directory to be enumerated. The scope argument specifies a criteria by 
which to search for files. 


The scope argument is a structure comprised of COUNT, DIRECTION, FILTER, and DEPTH. 


COUNT specifies the maximum number of files to be viewed by the client. The unlimitedCount 
constant may be specified as the value of COUNT to indicate that there is no limit to the files to be 
viewed. 


DIRECTION specifies the order in which files are enumerated. DIRECTION is used by those functions 
that list (display files in a specified direction) or search (display files that match a specific criteria). 
DIRECTION an enumerated type that accepts one of two values: FORWARD or BACKWARD. A value of 
FORWARD indicates that enumeration is to begin with the first file in the sequence of ordered files and 
end with the last. A value of BACKWARD indicates that enumeration is to begin with the last file in 
the sequence and end with the first. If DIRECTION is not specified, a FORWARD direction is assumed. 


FILTER is a set of Boolean operators and special characters that assist in differentiating files of 
interest. 


DEPTH is an integer that specifies the maximum number of levels down the directory hierarchy in 
which to search for files. A value of 1 indicates that only the files in the specified directory are to be 
considered. A value of 2 indicates that the directories immediately below the specified directory are 
also to be considered when searching for files. The allDescendants constant may be specified as the 
value of DEPTH to indicate that there is no restriction on the levels of directory hierarchy to descend. 
That is, all directories below the specified directory will be considered when searching for files. If 
DEPTH is not specified, a DEPTH of 1 is assumed. 


The controls argument specifies the access permissions to be applied to the new file handle. 
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The session argument is the client's session handle that was returned upon executing the Logon() 
function. 


RETURN VALUE 


This function returns a structure called FindResults. Its one member is handle is of type Handle. It 
contains the file handle of the first file that matches the search criteria. 


ERRORS 


Reports [AccessError[problem], AuthenticationError[problem], ControlTypeError, ControlValueError, 
HandleError, ScopeTypeError, ScopeValueError, SessionError[problem], UndefinedError] 
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Filing6_ _GetAttributes, ChangeAttributes 


NAME 


GetAttributes - retrieve the attributes of a file 
ChangeAttributes - modify file attributes 


SYNOPSIS 


#include <courier/Filing6 de.h> 
#include <courier/except.h> 


GetAttributesResults 
GetAttributes( Connection, BDTprocptr, file, types, session) 
COURIERFD- Connection; — 
int(* BDTprocptr)(); 
Handle file; 
AttributeTypeSequence types; 
Session session; 


void 
ChangeAttributes( Connection, BDTprocptr, file, attributes, session) 
COURIERFD Connection; 
int(* BDTprocptr)(); 
Handle file; 
AttributeSequence attributes; 
Session session; 


DESCRIPTION 


The GetAttributes() function is used to retrieve the attribute and attribute value pairs of a specific file. 
When this function is called, the File Service attempts to obtain the requested attributes and returns them 
to the requester. The ChangeAttributes() function is used to modify the access-related attributes of a 
specific file. 


The file argument is the file handle of the file whose attributes are to be retrieved or changed. Depending 
upon the changes to be made, you must have appropriate access permission. Write access is required if 
only data attributes are to be changed. Write access to the file's parent is required for environment-related 
attribute changes. Write access to the file's parent or owner access to the file itself is required if accessList 
or defaultAccessList attributes are to be changed. Changes made to a file's access list attributes takes 
immediate effect. All handles to the file within the current session and all new handles acquired later are 
affected. Access list changes made in the current session may not affect the existing sessions of other 
clients until those sessions are terminated. 


The types argument is a sequence of types for which the values are to be returned. The allAttributeTypes 
constant is acardinal number that may be specified as the value of the attributes argument to retrieve all 
the attributes of the file. The session argument is the client's session handle that was returned upon 
executing the Logon() function. 


The attributes argument is a sequence of the attributes to be changed. 


The session argument is the client's session handle that was returned upon executing the Logon() 
function. 
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RETURN VALUE 
GetAttributes() returns a structure called GetAttributesResults. Its one member, attributes, is of type 
AttributeSequence. It is a sequence of attributes that corresponds one-to-one with the items specified in 
the types argument. ChangeAttributes() returns void. 

ERRORS 


GetAttributes() reports [AccessError[problem], AttributeTypeError, AuthenticationError[problem], 

_ HandleError, SessionError[problem], UndefinedError] ChangeAttributes() reports 
[AccessError[problem], AttributeTypeError, AttributeValueError, AuthenticationError[problem], 
HandleError, InsertionError, SessionError[problem], SpaceError, UndefinedError] 


SEE ALSO 
Create(), Logon(), Open() 
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Filing6__GetControls, _ ChangeControls 


NAME 


GetControls - return the controls associated with a specific file 
ChangeControls - modify the controls associated with a specific file 


SYNOPSIS 


#include <courier/Filing6 de.h> 
#include <courier/except.h> 


GetControlsResults 
GetControls( Connection, BDTprocptr, file, types, session) 
COURIERFD Connection; 
int(* BDTprocptr)(); 
Handle file; 
ControlTypeSequence types; 
Session session; 


void 
ChangeControls( Connection, BDTprocptr, file, controls, session) 
COURIERFD "Connection; ~— 
int(* BDTprocptr)(); 
Handle file; 
ControlSequence controls; 
Session session; 


DESCRIPTION 


The GetControls() function is used to determine the file access associated with a specific file. Only the 
values of the specified controls will be returned. The ChangeControls() function is used to modify specific 
controls associated with a file. If a lock is specified, the File Service will attempt to acquire it, and if 
successful, any prior lock is released. Refer to Create() for more information regarding controls. 


The file argument is the file handle of the file from which to extract or change control values. The types 
argument is a sequence of integers that indicates the specific controls for which you are attempting to 
retrieve the values. The controls argument is a sequence of the control items to be reset. The session 
argument is the client's session handle that was returned upon executing the Logon() function. 


RETURN VALUE 
GetControls() returns a structure called GetControlsResults. Its one member, controls, is of type 
ControlSequence. It is a sequence of control items that corresponds one-to-one with the items specified in 
the types argument. ChangeControls() returns void. 

ERRORS 


GetControls() reports [AccessError[problem], AuthenticationError[problem], ControlTypeError, 
HandleError, SessionError[problem], UndefinedError]. ChangeControls() reports 
[AccessError[problem], AuthenticationError[problem], ControlTypeError, Control ValueError, 
HandleError, SessionError[problem], UndefinedError] 

SEE ALSO 


Create() 
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Filing6__List 


NAME 


List - display the files in a directory 


SYNOPSIS 


#include <courier/Filingé de.h> 
#include <courier/except.h> 


void 
List( Connection, BDTprocptr, directory, types, scope, listing, session) 
COURIERFD Connection; 
int(* BDTprocptr)(); 
Handle directory; 
AttributeTypeSequence types; 
ScopeSequence scope; 
~BulkData1 Descriptor listing; 
Session session; 


DESCRIPTION 


The List() function is used to enumerate the files in a directory and return desired attributes. The File 
Service enumerates the directory in accordance to its ordering attribute. The requested attributes of those 
files meeting desired criteria specified in the scope argument are returned. Since attributes are obtained 
with varying degrees of difficulty, it is recommended that you only request necessary attributes. 


The files in the directory may change at any time while this function is being executed. Therefore, it is 
possible that the set of files returned may not reflect the directory in its current state. If a depth greater 
than 1 is specified, then descendants of the specified directory must also be considered. To prevent changes 
from invalidating the results of List(), it necessary to acquire a SHARE lock on the directory before calling 
the List() function. 


The directory argument is of type Handle,. It is the file handle for the directory to be enumerated. 
nullHandle may be specified to indicate that enumeration is to begin with the root directory. Read access 


(i.e., read permission) is required of the directory to be enumerated. This also includes all the 


subdirectories to be enumerated. The types argument specifies a sequence of attributes a file must have to 
be considered. The allAttributeTypes constant may be specified as the value of types to indicate that all 
files are to be considered, regardless of the attributes they posses. 


The scope argument specifies a criteria by which to search for files. The scope argument is a structure 
comprised of COUNT, DIRECTION, FILTER, and DEPTH. See the description of scope in Find() for more 
information. 


The listing argument specifies the sink that is to receive the data in accordance to the Bulk Data Transfer 
Protocol. The transferred bulk data is of type StreamOfAttributeSequence. 


The session argument is the client's session handle that was returned upon executing the Logon() 
function. 


RETURN VALUE 
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This function returns void. 
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ERRORS 


Reports [AccessError[problem], AttributeTypeError, AuthenticationError[problem], ConnectionError, 
HandleError, ScopeTypeError, ScopeValueError, SessionError[problem], TransferError[problem], 
UndefinedError] 


SEE ALSO 
Find(), Open(), Logon() 
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Filing6__Logoff 


NAME 


Logoff - end acurrent File Service session 


SYNOPSIS 


#include <courier/Filing6 de.h> 
#include <courier/except:h> 


void | 
Logoff( Connection, BDTprocptr, session) 
COURIERFD Connection; 
int(* BDTprocptr)(); 
Session session; 
DESCRIPTION 


The Logoff() function is used to end the current File Service session. Upon calling this function, the File 
Service verifies that the request is valid, terminates the session, releases any allocated resources, and 
then invalidates the session handle. The session argument is the session handle returned by a call to 
Logon(). 


RETURN VALUE 


This function returns void. 


ERRORS 


Reports [AuthenticationError[problem], ServiceError[problem], SessionError[problem], UndefinedError] 


SEE ALSO 
Logon() 
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Filing6__Logon 


NAME 


Logon - begin a File Service session 


SYNOPSIS 


#include <courier/Filing6 de.h> 
#include <courier/except.hA> 
#include <courier/FilingSu1.h> 


LogonResults 
Logon( Connection, BDTprocptr, service, credentials, verifier) 
COURIERFD Connection; 
int(* BDTprocptr)(); 
ThreePartName service; 
Credentials credentials; 
Verifier verifier; 


DESCRIPTION 


The Logon() function is used to initiate access to a File Service. This function must be executed before any 
other Filing Protocol function. If the File Service verifies that the Logon request is valid, it will create a 
session, and return a session handle. This session handle is an identifier that must accompany any other 
filing function call. 


The service argument is the name of the Filing Service to be accessed. If a service is not explicitly 
specified, and thus the service name is left null, a default service is provided by the installed XNS system. 
The credentials and verifier arguments identify the client, or user, initiating a File Service session. 
credentials may be in one of several forms: primary, secondary, or encrypted secondary.The verifier is the 
simple verifier returned earlier by the Authentication Service. 


RETURN VALUE 


This function returns a pointer to a structure, called LogonResults. This structure is similar to the 
session structure and is also referred to as the session handle. Its one member, session, is of type Session. 
It is a structure having two members: token and verifier. The token array identifies the session to the File 
Service, thereby identifying the user and the status of the user's interaction with the File Service. The 
session token, once returned, is to be used in subsequent function calls to the File Service within the same 
session. The token remains static for the duration of the session and it cannot be interpreted by the client. 
The verifier array is defined by the Authentication Protocol. It verifies that all function calls using the 
same session handle have been originated from the same client that originally established the session. 
The verifier is not static and may change with each new function call. 


ERRORS 


Reports [AuthenticationError[problem], ServiceError[problem], SessionError[problem], UndefinedError] 
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Filing6__Move 


NAME 


Move - move a file to another directory 


SYNOPSIS 


#include <courier/Filing6 de.h> 
#include <courier/except.h> 


void 
Move( Connection, BDTprocptr, file, destinationDirectory, attributes, session) 
COURIERFD Connection; 
int(* BDTprocptr)(); 
Handle file; 
Handle destinationDirectory; 
AttributeSequence attributes; 
Session session; 


DESCRIPTION 


The Move() function is used to change the directory structure of the filing service without creating or 
deleting files. The File Service moves a file or directory to a specific directory location. If the specified file 
is a child of another directory, it is removed from that directory. If a temporary file is specified, it is made 
permanent. If the specified file has descendants, they will remain as such and will be moved along with 
the file. A file cannot be moved into itself or any of its descendants. 


The file argument is the file handle of the file or directory to be moved. Read and write access (i.e., read 
and write permission) is required of the file or directory to be moved. Remove access is required of the 
file's parent directory. There can be only one file handle in use during the current session for the file 
specified. If there is more than one file handle in use for a file, it cannot be moved. 


The destinationDirectory argument is the file handle for the directory in which the file is to be placed. Add 
access (i.e., write permission) is required of the destination directory. The attributes argument specifies 
the sequence of characteristics to be assigned to the new file or directory, thus overriding those of the 
original file or directory. The session argument is the client's session handle that was returned upon 
executing the Logon() function. 


RETURN VALUE 


This function returns void. 


ERRORS 
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Reports [AccessError[problem], AttributeTypeError, AttributeValueError, 
AuthenticationError[problem], ControlTypeError, Control ValueError, HandleError, InsertionError, 
SessionError[problem], SpaceError, UndefinedError] 
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Filing6__Open 


NAME 


Open - make a file available for use 


SYNOPSIS 


#include <courier/Filing6 de.h> 
#include <courier/except.h> 


OpenResults 
Open( Connection, BDTprocptr, attributes, directory, controls, session) 
COURIERFD Connection; 
int(* BDTprocptr)(); 
AttributesSequence attributes; 
Handle directory; 
ControlSequence controls; 
Session session; 


DESCRIPTION 


The Open() function is used to make a file available for use. Once this function is called, the file server 
prepares the specified file for use, applies specific controls to it, then creates and returns a file handle. The 
file is marked “in use" and attempts to move or delete it by other sessions is ignored. 


The attributes argument identifies the file to be opened. It requires six parameters: parentiD, filelD, 
name, pathname, type, and version. parentiID specifies the starting directory in which may be found a file 
containing the same ID as that specified in the filelD parameter. If parentID is omitted, the starting 
directory is the root directory. 


filelD identifies the file that is to be opened. If parentiD or directory is included in the function call, the 
specified file must be a child of the starting directory. If neither of the two is specified, the file may be 
anywhere. The name parameter supplies the name of the file to be opened. The file specified in this 
parameter must be a child of the starting directory. The pathname parameter specifies the path name of 
the file to be opened. The first component of pathname must be a child of the starting directory. If the 
starting directory is omitted, the root directory is used. The client must have the appropriate access 
permissions for every file specified in the path name. The type parameter indicates the file type of the 
object to be opened. The version parameter specifies the version number of the file to be opened. If the 
parameter is omitted, the file with the highest version number is opened. This parameter is ignored if the 
last file named in the pathname argument explicitly states the version number. This parameter is 
specified only if the name parameter or pathname parameter is used. 


The sequence for specifying the attributes are as follows. The brackets indicate optional parameters: 


a) filelD [parentiD] [type] 
b) name [parentID] [type] [version] 
c) pathname [parentID] [type] [version] 


The directory argument specifies a starting directory from which to begin the search for the file specified 
in the attributes argument. nullHandle may be specified in the directory argument rather than a valid 
session handle. nullHandle is a reserved constant with special significance. It may be used in functions, 
like Open(), to imply the root directory. Unless specifically stated, a nullHandle is not to be used as an 
argument value. | 
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RETURN VALUE 


This function returns a structure called OpenResults. Its one member, handle, is of type Handle. It is the 
file handle for the file identified by the attributes argument. It is to be passed as an argument to all 
further calls to functions that are to access the file during the current session. 


ERRORS 


Reports [AccessError[problem], AttributeTypeError, AttributeValueError, 
AuthenticationError[problem], ControlTypeError, Control ValueError, HandleError, 
SessionError[problem], UndefinedError] 


SEE ALSO 
Logon() 
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Filing6__Replace 


NAME 


Replace - replace the contents of a file 


SYNOPSIS 


#include <courier/Filing6 de.h> 
#include <courier/except-h> 


void 
Replace( Connection, BDTprocptr, file, attributes, content, session) 
COURTERFD Connection; 
int(* BDTprocptr)(); 
Handle file; 
AttributeSequence attributes; 
BulkData1 Descriptor content; 
Session session; 


DESCRIPTION 
The Replace() function is used to remove the contents of a file and then replace it with data received froma 


specific source. 


The file argument is the file handle for the file whose contents is to be replaced. Write access (i.e., write 
permission) is required of the specified file. The attributes argument specifies the sequence of 
characteristics to be assigned to the resulting file. The content argument specifies the source that is to 
supply the data to go in the replacement file in accordance with the Bulk Data Transfer Protocol. The 
session argument is the client's session handle that was returned upon executing the Logon() function. 


RETURN VALUE 


This function returns void. 


ERRORS 


Reports [AccessError[problem], AttributeTypeError, AttributeValueError, 
AuthenticationError[problem], ConnectionError, HandleError, SessionError[problem], SpaceError, 
TransferError[problem], UndefinedError] 
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Filing6__ Retrieve 


NAME 


Retrieve - extract the contents of a file 


SYNOPSIS 


#include <courier/Filing6 de.h> 
#include <courier/except.h> 


void 
Retrieve( Connection, BDTprocptr, file, content, session) 
COURTERFD Connection; 
int(* BDTprocptr)(); 
Handle file; 
BulkData1 Descriptor content; 
Session session; 


DESCRIPTION 


The Retrieve() function is used to read the contents of an existing file and transfer them to the client. 


The file argument is the file handle of the file from which the contents are to be retrieved. Read access (i.e., 
read permission) is required of the specified file. The content argument specifies the sink that is to receive 
the contents of the file in accordance with the Bulk Data Transfer Protocol. The session argument is the 
client's session handle that was returned upon executing the Logon() function. 


RETURN VALUE 


This function returns void. 


ERRORS 


Reports [AccessError[problem], AuthenticationError[problem], ConnectionError, HandleError, 
SessionError[problem], TransferError[problem], UndefinedError] 
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Filing6__RetrieveBytes, ReplaceBytes 


NAME 


RetrieveBytes - read bytes within a file 
ReplaceBytes - modify the contents of a file 


SYNOPSIS 


#include <courier/Filing6é de.h> 
#include <courier/except.h> 


void 
RetrieveBytes( Connection, BDTprocptr, file, range, sink, session) 
COURIERFD- Connection; — 
int(* BDTprocptr)(); 
Handle file; 
ByteRange range; 
BulkData1 Descriptor sink; 
Session session; 


void 
ReplaceBytes( Connection, BDTprocptr, file, range, source, session) 
COURIERFD Connection; 
int(* BDTprocptr)(); 
Handle file; 
ByteRange range; 
BulkData1 Descriptor source; 
Session session; 


DESCRIPTION 


The RetrieveBytes() function is used to read a range of bytes within a file. The ReplaceBytes() function is 
used to overwrite the contents of a file or to append new data to a file. 


The file argument is the file handle for the file from which to retrieve a range of bytes or modify a range of 
bytes. Read access (i.e., read permission) is required of the file from which you want to retrieve data. Write 
access (i.e., write permission) is required of the file to be modified. 


When calling RetrieveBytes(), the range argument is of type ByteRange. It specifies the contiguous 
sequence of bytes to be returned. When calling ReplaceBytes(), the range argument specifies the file 
location, in bytes, where data is to be inserted and the total number of bytes to be inserted. The value of 
the range argument and the data supplied by the source must be the same. If the firstByte parameter of 
the range argument is set to endOfFile, the supplied data is appended to the specified file. Otherwise, the 
supplied data replaces the file data that starts at the specified file location, ending at however many bytes 
are specified for the length. In the case of appending data, this function insures that all the data is 
successfully appended or it will not modify the file at all. 


ByteRange is a structure comprised of ByteAddress and ByteCount. These two members specify the 
byte offset at which to begin storing or retrieving data and the number of bytes to store or retrieve, 
respectively. ByteAddress is a LongCardinal number. The value specified cannot exceed the total size 
in bytes of the file. Call the GetAttributes() function with the dataSize argument to ascertain the total 
size in bytes of the file. ByteCount is a LongCardinal number that indicates the total number of 
contiguous bytes to store or retrieve. The value specified, when added to the offset, cannot exceed the 
total size in bytes of the file. 


The endOfFile constant is a LongCardinal number that may be used as the value of ByteAddress or 
ByteCount to refer to the logical end of a file. As a byte address, endOfFile is used to refer to the byte 
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position at the end of a file where new data can be appended. When used as a ByteCount, endOfFile 
may be used to represent the number of bytes that begins at the specified offset and ends at the last 
byte defined for the file. 


The sink argument specifies the sink that is to receive the requested data bytes in accordance with the 
Bulk Data Transfer Protocol. The source argument specifies the source that is to supply the data bytes in 
accordance with the Bulk Data Transfer Protocol. 


The session argument is the client's session handle that was returned upon executing the Logon() 
function. 


RETURN VALUE 


These functions return void. 


ERRORS 


Reports [AccessError[problem], HandleError, RangeError, SessionError[problem], UndefinedError] 


SEE ALSO 
GetAttributes(), Open(), Logon() 


8-60 - | DOCUMENT INTERFACES TOOLKIT SYSTEM REFERENCE 


XNS LIBRARY 


Filing6__Serialize, _ Deserialize 


NAME 


Serialize - encode a file 
Deserialize - unencode a file 


SYNOPSIS 


#include <courier/Filing6é de.h> 
#include <courier/except.h> 


void 
Serialize( Connection, BDTprocptr, file, serializedFile, session) 
COURTERFD Connection; 
int(* BDTprocptr)(); 
Handle file; 
BulkData1 Descriptor serializedFile; 
Session session; 


DeserializeResults 
Deserialize(_ Connection, BDTprocptr, directory, attributes, controls, serializedFile, session) 
COURIERFD Connection; 
int(* BDTprocptr)(); 
Handle directory; 
AttributeSequence attributes; 
ControlSequence controls; 
BulkData1 Descriptor serializedFile; 
Session session; 


DESCRIPTION 


The Serialize() function is used to compress all the descriptive information and data of a file and its 
descendants into a series of eight-bit bytes. The resulting data is a single object of type SerializedFile. This 
object is then transferred to a sink. It is necessary to serialize a file in order to transfer it to another File 
Service or store it on some other medium. 


The Deserialize() function is used to reconstruct a file and its descendants from a previously serialized file. 
When this function is called, a new file is created in the specified directory and a file handle for the new 
file is returned. The new file will have most of the attributes, all the contents and all the descendants as it 
did prior to serialization. Some attributes are ignored during deserialization because the attribute 
duplicates information that is implicit to other data. For example, the numberOfChildren attribute is 
ignored because the number of descendants a file has is already encoded in the serialized file. If the name 
of the deserialized file duplicates that of an existing file, the deserialized file is created with an 
appropriate version number. The existing file is not replaced by the deserialized file. 


The file argument is the file handle for the file whose contents is to be serialized. Read access (i.e., read 
permission) is required of the specified file. 


The serializedFile argument, either, specifies the sink that is to receive the compressed file contents in the 
case of Serialize(), or specifies the source that is to supply the serialized file data in the case of 
Deserialize(). The specifications are made in accordance to the Bulk Data Transfer Protocol. 


The directory argument is a handle of the directory in which the new file is to be placed. directory may be 
set to nullHandle, thus indicating that the resulting file is to be placed in the root directory. Add access 
(i.e., write permission) is required of the destination directory if the file handle specified is not nullHandle. 
The attributes argument specifies the sequence of characteristics to be assigned to the new file, thus 
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overriding the default characteristics inherent to the serialized file. The controls argument specifies the 
access permissions to be applied to the new file handle. 


The session argument is the client's session handle that was returned upon executing the Logon() 
function. 


RETURN VALUE 


The Serialize function returns void. The Deserialize function returns a structure called 
DeserializeResults. Its one member, file, is of type Handle. It is the file handle for the file identified in the 
attributes argument. 


ERRORS 


Serialize reports [AccessError[problem], AuthenticationError[problem], ConnectionError, HandleError, 
sessionError[problem], TransferError[problem], UndefinedError] Deserialize reports 
[AccessError[problem], AttributeTypeError, AttributeValueError, AuthenticationError[problem], 
ConnectionError, ControlTypeError, ControlValueError, HandleError, InsertionError, 
SessionError[problem], SpaceError, TransferError[problem], UndefinedError] 


SEE ALSO 
Open(), Logon() 
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Filing6___ Store 


NAME 


Store - create a file 


SYNOPSIS 


#include <courier/Filing6é de.h> 
#include <courier/except.h> 


StoreResults 
Store( Connection, BDTprocptr, directory, attributes, controls, content, session) 
COURIERFD Connection; 
int(* BDTprocptr)(); 
Handle directory; 
AttributeSequence attributes; 
ControlSequence controls; 
BulkData1 Descriptor content; 
Session session; 


DESCRIPTION 


The Store() function is used to create a file that contains specific data. When this function is called, a new 
file is created with specific attributes and is placed in a specified directory. It is then filled with data sent 
by the client in accordance to the Bulk Data Transfer Protocol. Upon completion, a file handle is returned 
for the new file. 


The directory argument is the file handle for the directory in which the new file is to be placed. nullHandle 
may be specified to indicate that the resulting file is to be placed in the root directory. Add access (i.e., 
write permission) is required of the destination directory if the file handle specified is not nullHandle. The 
attributes argument specifies the sequence of characteristics to be assigned to the new file. The controls 
argument specifies the access permissions of the new file. The content argument specifies the source that 
is to supply the contents of the new file in accordance with the Bulk Data Transfer Protocol. The session 
argument is the client's session handle that was returned upon executing the Logon() function. 


RETURN VALUE 


This function returns a structure called StoreResults. Its one member, file, is of type Handle. It is the file 
handle for the file identified in the attributes argument. 


ERRORS 


Reports [AccessError[problem], AttributeTypeError, AttributeValueError, 
AuthenticationError[problem], ConnectionError, ControlTypeError, Control ValueError, HandleError, 
InsertionError, SessionError[problem], SpaceError, TransferError[problem], UndefinedError] 


SEE ALSO 


Retrieve() 
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Filing6__UnifyAccessLists 


NAME 


UnifyAccessLists - group the access lists of a subtree of files 


SYNOPSIS 


#include <courier/Filing6 de.h> 
#include <courier/except.h> 


void 
UnifyAccessLists( Connection, BDTprocptr, directory, session) 
COURIERFD Connection; ~~ 
int(* BDTprocptr)(); 
Handle directory; 
Session session; 


DESCRIPTION 


The UnifyAccessLists() function is used to assign the access list attributes (i.e., permissions) of a directory 
to all its descendants. The file argument is the file handle of the directory. Write access is required of the 
directory specified as well as all its descendants. The session argument is the client's session handle that 
was returned upon executing the Logon() function. 


Changes made to access list attributes takes immediate effect. All handles to the files within the current 
session and all new handles acquired later are affected. Access list changes made in the current session 
may not affect the existing sessions of other clients until those sessions are terminated. 


RETURN VALUE 


This function returns void. 


ERRORS 


Reports [AccessError[problem], AuthenticationError[problem], HandleError, SessionError[problem], 
UndefinedError] 


SEE ALSO 
Logon(), Open() 
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Gap3__Create 


NAME 


Create - start terminal emulation 


SYNOPSIS 


#include <courier/Gap3 de.h> 
#include <courier/except.h> 


void 
Create( Connection, BDTprocptr, sessionParameterHandle, transportList, createTimeout, credentials, 
verifier) _ _ 

COURIERFD Connection; 

int(* BDTprocptr)(); 

SessionParameterObject sessionParameterHandle; 

T p3 3 18transportList; 

Cardinal createTimeout; 

Credentials credentials; 

Verifier verifier; 


DESCRIPTION 


The Create() function is used to initiate a terminal emulation session with a mainframe computer system. 
Terminal devices such as TTY, VT100, IBM 3270, etc. can be emulated. This makes it possible for nonXNS 
terminal devices to interconnect with an XNS system and access XNS services. For this reason, the 
Gateway Access Protocol (GAP) is also referred to as the Virtual Terminal Protocol (VTP). 


When a workstation client requests an emulation session with a host computer, the workstation uses the 
Clearinghouse to locate an External Communication Service (ECS) that supports connections with a 
specified host. The workstation then connects to the ECS which initiates a session with the remote host 
and performs conversions between the XNS and remote host protocols. The protocol conversion provided 
by the ECS allows information originating from the mainframe computer or anywhere else on the XNS 
internet to be transferred to and from the mainframe environment and the system on which Create() was 
invoked. 


The sessionParameterHandle argument is a structure that supplies the host system all the pertinent 
information necessary for the local workstation to emulate a specific terminal. Acceptable terminal types 
are: XEROX800, XEROX850, XEROX860, SYSTEM6, CMCLL, IBM2770, IBM2770HOST, IBM6670, 
IBM6670HOST, IBM3270, IBM3270HOST, OLDTTYHOST, OLDTTY, OTHERSESSIONTYPE, UNKNOWN, 
IBM2780, IBM2780HOST, IBM3780, IBM3780HOST,SIEMENS9750, SIEMENS9750HOST, TTYHOST, and 
TTY. 


Some of these terminal types require some additional information. MEROX860 requires pollProc. 
IBM6670HOST requires the block size of the transmit and receive packets. OLDTTY requires the length ofa 
byte (five, six, seven, or eight bits to a byte), parity (none, odd, even, one, or zero), the stop bit (oneStopBit, 
twoStopBits), and the frameTimeout (integer indicating milliseconds). IBM3780HOST requires the block 
size of the transmit and receive packets. And TTY has the same requirements as OLDTTY, plus flowControl 
(flowControlNone or XOn/XOff). 


The transportList argument specifies the device that is to receive data. Devices include a modem on an 
RS232 line, teletype, various BSC terminals and controllers, and so on. Acceptable types are: RS232C, BSC, 
TELETYPE, POLLEDBSCCONTROLLER, POLLEDBSCTERMINAL, SDLCCONTROLLER, SDLCTERMINAL, 
SERVICE, UNUSED, POLLEDBSCPRINTER, and SDLCPRINTER. 
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The createTimeout argument is an integer that specifies the number of seconds to wait for a 
connection to the mainframe computer before aborting the attempt. 


The credentials argument is the credentials returned earlier by the Authentication Service. The 
credentials may be either simple or strong. The client cannot switch from simple to strong authentication 
or visa versa within the same session. The verifier argument is the simple verifier acquired at the same 
time as the credentials . 


RETURN VALUE 


This function returns void. 


ERRORS 


Reports [badAddressFormat, controllerAlreadyExists, controllerDoesNotExist, 
dialingHardwareProblem, illegalTransport, inconsistentParams, mediumConnectFailed, 
noCommunicationHardware, noDialingHardware, terminalAddressInUse, terminalAddressInvalid, 
tooManyGateStreams, transmissionMediumUnavailable, serviceTooBusy, userNotAuthenticated, 
userNotAuthorized, serviceNotFound] ; 
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Inbasket2__ChangeBodyPartsStatus 


NAME 


ChangeBodyPartsStatus - update the status of message body parts 


SYNOPSIS 


#include <courier/nbasket2 de.h> 
#include <courier/except.h> | 


ChangeBodyPartsStatusResults 
ChangeBodyPartsStatus( Connection, BDTprocptr, index, setStatusTo, session) 
COURIERFD Connection; 3 
int(* BDTprocptr)(); 
LongCardinal index; 
BodyPartsStatusChangeSequence setStatusTo; 
Session session; 


DESCRIPTION 


The ChangeBodyPartsStatus() function is used to update the status of one or more message body parts. 
When all the body parts of a message have been set to deletable, the entire message will be deleted by the 
mail service. Therefore, if the client wants data from a body part, be sure to store the data before the status 
is changed to deletable. Once the status of a part part has been changed to deletable, it is irreversible. All 
the parts of a message are accessible until the entire message is deleted. This function also updates the 
MessageStatus field to KNOWN. 


The index argument is the index number of the message to be updated. The setStatusTo argument is a 
structure having two members: bodyPartindex and deletable. Together, they define the body parts to be 
modified. The bodyPartindex member specifies the part in accordance to the 
MailTransportEnvelopeFormat. The deletable member is a an enumerated type that may contain one of 
two values: TRUE or noChange. 


The session argument is the inbasket session handle returned by a preceding call to Logon(). 


RETURN VALUE 


This function returns a structure called ChangeBodyPartsStatusResults. Its one member, deleted, is a 
Boolean that indicates the success of the operation. A value of TRUE indicates that all the body parts of the 
message have been marked as being deletable. | 


ERRORS 


Reports [AuthenticationError[problem], IndexError[problem], OtherError[problem], 
SessionError[problem], ServiceError[problem], Courier Errors: REJECT_ERROR, SYSTEM_ ERROR, 
default] 
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Inbasket2__ChangeMessageStatus 


NAME 


ChangeMessageStatus - change message status from new to known 


SYNOPSIS 


#include <courier/Inbasket2 de.h> 
#include <courier/except.h> _ 


void 
ChangeMessageStatus( Connection, BDTprocptr, range, changeUserDefinedStatus, 
newUserDefinedStatus, session) = 

COURIERFD Connection; 

int(* BDTprocptr)(); 

Range range; 

Boolean changeUserDefinedStatus; 

Cardinal newUserDefinedStatus; 

Session session; 


DESCRIPTION 


The ChangeMessageStatus() function is used to update a specified range of messages from new to known. 
This function may also be used to update the userDefinedStatus. 


The range argument specifies a set of messages whose status is to be updated from new to known. It 
requires two parameters. The two parameters are integers that specify the low and high message indices 
between which all the messages are to be changed. The messages corresponding to the low and high 
indices will also be affected. The constant nulllndex may be used as a value for one or both of the 
parameters. For example, if the value of range is (nulllndex, 5) then all the messages between the first 
inbasket message up to the fifth, inclusive, are updated to known. If (5, nulllndex) is specified, then all the 
messages between the fifth and last, inclusive, are affected. A value of (nulllndex, nulllndex) may be 
specified to indicate that all the messages in the inbasket are to be affected. Once a message has been 
updated to known, it can never be reverted back to new. Attempts to do will be ignored. 


The changeUserDefinedStatus argument is a Boolean value that indicates whether or not the user defined 
status should be changed. When set to TRUE, changeUserDefinedStatus causes existenceOfMessage to be 
set to KNOWN and userDefinedStatus to be updated with the value of newUserDefinedStatus. The default 
is FALSE. 


The newUserDefinedStatus argument is an integer that specifies the new value of the messages specified 
in the range argument. This user defined status is not interpreted by the mail service. It serves only for 
use by sophisticated clients to attach arbitrary status information to a message. Only the client who 
attaches the status information may retrieve it. The range of acceptable values are cardinal numbers 
between 0 and 65,535, inclusive. 


The session argument is the inbasket session handle returned by a preceding call to Logon(). 


RETURN VALUE 


This function returns void. 


ERRORS 
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Reports [AuthenticationError[problem], IndexError[problem], OtherError[problem], 
SessionError[problem], ServiceError[problem], TransferError[problem], Courier Errors: 
REJECT__ERROR, SYSTEM_ ERROR, default] 
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Inbasket2_ Delete 


NAME 


Delete - remove messages from the inbasket 


SYNOPSIS 


#include <courier/Inbasket2 de.h> 
#include <courier/except.h> 


void 
Delete( Connection, BDTprocptr, range, session) 
COURIERFD Connection; 
int(* BDTprocptr)(); 
Range range; 
Session session; 


DESCRIPTION 


The Delete() function is used to remove one or more contiguous messages from the inbasket. If there are 
no messages within the range of specified indices, no error is returned. 


The range argument specifies the set of messages to be deleted. It requires two parameters. The two 
parameters are integers that specify the low and high message indices between which all the messages are 
to be deleted. The messages corresponding to the low and high indices will also be deleted. The constant 
nulllndex may be used as a value for one or both of the parameters. For example, if the value of range is 
(nulllndex, 5) then all the messages between the first inbasket message up to the fifth, inclusive, will be 
deleted. If (5, nulllndex) is specified, then all the messages between the fifth and last, inclusive, will be 
deleted. A value of (nulllndex, nulllndex) may be specified to indicate that all the messages in the inbasket 
are to be deleted. 


The session argument is the inbasket session handle returned by a preceding call to Logon(). 


RETURN VALUE 


This function returns void. 


ERRORS 


Reports [AuthenticationError[problem], OtherError[problem], SessionError[problem], 
ServiceError[problem], Courier Errors] 
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Inbasket2__GetSize 


NAME 


GetSize - retrieve the size of the inbasket 


SYNOPSIS 


#include <courier/Inbasket2 de.h> 
#include <courier/except.h> _ 


GetSizeResults 
GetSize( Connection, BDTprocptr, inbasket, credentials, verifier) 
COURTERFD Connection; 
int(* BDTprocptr)(); 
ThreePartName inbasket; 
Credentials credentials; 
Verifier verifier; 


DESCRIPTION 
The GetSize() function is used to retrieve a tally of the disk space occupied by all the messages in an 
inbasket The value returned is in units of bytes. 


The inbasket argument is a structure of type ThreePartName. Its three members, organization, domain, 
and object, identify the mail recipient. The recipient must be registered with the Clearinghouse. Usually 
the value of the inbasket argument is the same as the user identified in the credentials. UNIX wildcards 
may not be used to specify any part of the name. Aliases are allowed and are resolved by the Mail Service. 


The credentials argument is the credentials returned earlier by the Authentication Service. The verifier 
argument is the verifier returned earlier by the Authentication Service. 


RETURN VALUE 


This function returns a structure called GetSizeResults. Its one member, sizelnBytes, is a cardinal number 
that indicates the total number of bytes being used by the specified inbasket. 


ERRORS 


Reports [AuthenticationError[problem], AccessError[problem], OtherError[problem], | 
ServiceError[problem], Courier Errors: REJECT_ERROR, SYSTEM_ ERROR, default] 
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Inbasket2__Logon, _ Logoff 


NAME 


Logon - initiate a new inbasket session 
Logoff - terminate an inbasket session 


SYNOPSIS 


#include <courier/Inbasket2 de.h> 
#include <courier/except.h>_ 


LogonResults 
Logon( Connection, BDTprocptr, inbasket, credentials, verifier) 
COURIERFD Connection; 
int(* BDTprocptr)(); 
ThreePartName inbasket; 
Credentials credentials; 
Verifier verifier; 


void 

Logoff( Connection, BDTprocptr, session) 
COURIERFD Connection; 
int(* BDTprocptr)(); 
Session session; 


DESCRIPTION 


The Logon() function is used to initiate a new inbasket session with the mail service. Once an inbasket 
session has been initiated, the client may access messages sent to the user specified in the credentials. The 
Logoff() function is used to end an inbasket session with the mail service. The inbasket session handle will 
then become invalid. 


Most inbasket operations take place within the context of a session. Each session references a single 
inbasket that is specified when the session is initiated. The name of the inbasket will be the same as the 
name of the message recipient. The message recipient does not have to be same person as specified in the 
credentials that were used to authorize the inbasket session. More than one session may access the same 
inbasket simultaneously. When this occurs, each session is cognizant of changes made by the other 
session(s). 


The inbasket argument is a structure comprised of organization, domain, and object name. It is used to 
identify the mail recipient for whom an inbasket session is being initiated. The recipient must be 
registered with the Clearinghouse. Usually the value of the inbasket argument is the same as the user 
identified in the credentials. UNIX wildcards may not be used to specify any part of the name. Aliases are 
allowed and are resolved by the Mail Service. The name is to be the same as the inbasket name that was 
initially assigned by the System Administrator. 


The credentials argument is the credentials returned earlier by the Authentication Service. This 

argument is used to by the Authentication Service to unequivocally determine a client’s right to access the 

specified inbasket. The credentials may be either simple or strong credentials. If the user specified in the 
_inbasket argument is not the same as that identified by the credentials, the client must have strong 

credentials to initiate the inbasket session. The verifier argument is the verifier returned by the 
- Authentication Service. 


The session argument is the inbasket session handle returned by a preceding call to Logon(). 
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RETURN VALUE 


The Logon() function returns a structure called LogonResults. It contains three members: session, state, 
and anchor. session is of type Session. Its one member, token, is of type T 118 2 63. token is an 
unspecified array that is used as an identifier. It should be passed unchanged to all operations within the 
same session. 


state is a structure of type State. It contains two members, new and total. new is a cardinal number 
that indicates the number of new, or unread, messages in the inbasket. total is a cardinal number that 
indicates the sum total of all the messages in the inbasket. The values returned by new and total 
reflect only those changes that have been made permanent. 


anchor is a five-wide integer of type Anchor. It is used to determine the validity of the mailing service 
cached indices. Each message in an inbasket is identified by a unique index which is permanently 
assigned to each message. Indices are positive integers allocated from a 32-bit field. On occasion, the 
association of an index to a message becomes invalid due to such events as, shuttling an inbasket 
between mail services. 


The anchor is especially important when the same message indices are used in more than one inbasket 
session. If the same indices are used, the anchor returned by each call to Logon() should be stored and 
compared against the anchors returned by each succeeding call to Logon(). If the anchor returned by a 
call to Logon() is different than that of a preceding call to Logon(), then the previously cached indices 
are invalid. When this occurs, flush the old values from the cache(s) in order to maintain accurate 
indices of the messages in the mail box. When a client is aware that an index has become invalid 
during the course of an inbasket session, the client may assume that the message referenced by the 
invalid index has been deleted by another client. 


The Logoff() function returns void. 


ERRORS 


Logon() reports [AccessError[problem], AuthenticationError[problem], InbasketInUse, 
OtherError[problem], ServiceError[problem], Courier Errors: REJECT__ERROR, SYSTEM__ERROR, 
default]. Logoff() reports [AuthenticationError[problem], OtherError[problem], SessionError[problem], 
Courier Errors: REJECT_ERROR, SYSTEM_ ERROR, default] 
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Inbasket2__MailCheck 


NAME 


MailCheck - check an inbasket from within a session 


SYNOPSIS 


#include <courier/Inbasket2 de.h> 
#include <courier/except.h> 


MailCheckResults 
MailCheck( Connection, BDTprocptr, session) 
COURIERFD Connection; 
int(* BDTprocptr)(); 
Session session; 
DESCRIPTION 
The MailCheck() function is used to determine the state of an inbasket. Unlike MailPoll(), this function is 
to be used during an inbasket session. 
The session argument is the inbasket session handle returned by a preceding call to Logon(). 


RETURN VALUE 


This function returns a structure called MailCheckResults. Its one member, state, is of type State. It is a 
structure having two members: new and total. new is a cardinal number that indicates the number of 
new, or unread, messages in the inbasket. total is a cardinal number that indicates the sum total of all the 
messages in the inbasket. The values returned by new and total reflect only those changes that have been 
made permanent. 


ERRORS 


Reports [AuthenticationError[problem], OtherError[problem], SessionError[problem], 
ServiceError[problem], Courier Errors: REJECT__ERROR, SYSTEM_ ERROR, default] 


SEE ALSO 
Logon() 
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Inbasket2_ MailPoll 


NAME 


MailPoll - check an inbasket without starting a session 


SYNOPSIS 


#include <courier/Inbasket2 de.h> 
#include <courier/except.h>_ 


MailPollResults 
MailPoll( Connection, BDTprocptr, inbasket, credentials, verifier) 
COURTERFD Connection; 
int(* BDTprocptr)(); 
ThreePartName inbasket; 
Credentials credentials; 
Verifier verifier; 


DESCRIPTION 


The MailPoll() function is used to quickly determine the state of an inbasket. This function is fast because 
the client does not incur the overhead of initiating an inbasket session. 


The inbasket argument is a structure of type ThreePartName. Its three members, organization, domain, 
and object, identify the mail recipient. The recipient must be registered with the Clearinghouse. Usually 
the value of the inbasket argument is same as the user identified in the credentials. UNIX wildcards may 
not be used to specify any part of the name. If the object name encountered is an alias, it is de-referenced 
before it is processed. The Mail Service will resolve aliases. 


The credentials argument is the credentials returned earlier by the Authentication Service. The verifier 
argument is the verifier returned earlier by the Authentication Service. 


RETURN VALUE 


This function returns a structure called MailPollResults. Its one member, state, is a structure of type 
State. state has two members: new and total. new is a cardinal number that indicates the number of new, 
or unread, messages in the inbasket. total is a cardinal number that indicates the sum total of all the 
messages in the inbasket. The values returned by new and total reflect only those changes that have been 
made permanent. 


ERRORS 


Reports [AccessError[problem], AuthenticationError[problem], OtherError[problem], 
SessionError[problem], Courier Errors: REJECT_ERROR, SYSTEM _ ERROR, default] 


SEE ALSO 
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MailCheck() 
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Inbasket2__RetrieveBodyParts 


NAME 


RetrieveBodyParts - extract specific body parts of a message 


SYNOPSIS 


#include <courier/Inbasket2 de.h> 
#include <courier/except.h> 


void 
RetrieveBodyParts( Connection, BDTprocptr, message, bodyParts, contents, session) 
COURIERFD Connection; ~~ 
int(* BDTprocptr)(); 
LongCardinal message; 
BodyPartSequence bodyParts; 
BulkData1 Descriptor contents; 
Session session; 


DESCRIPTION 
The RetrieveBodyParts() function is used to copy specific parts of an inbasket message from the outbasket 


to the client’s local disk. 


The _ BDTprocptr argument is the name of the client-defined function that will be retrieving the body 
parts. This function must be provided. 


The message argument is the index number of the message from which body parts are to be retrieved. The 
bodyParts argument may be either a list of individual body parts or the constant allBodyParts. Body parts 
are retrieved in the order they are specified in the BodyPartSequence parameter. 


The contents argument is the stream of body part data in which the returned parts are to be placed in 
accordance to the Bulk Data Transfer Protocol. The returned body parts are concatenated without any 
structure-related information separating them. The client can determine the starting point of each body 
part by using the part sizes listed in the tableOfContents. Use BulkDatal_immediateSink when 
retrieving to a local file. 


The session argument is the inbasket session handle returned by a preceding call to Logon(). 


RETURN VALUE 


This function returns void. 


ERRORS 


Reports [AuthenticationError[problem], IndexError[problem], OtherError[problem], 
SessionError[problem], ServiceError[problem], TransferError[problem], Courier Errors: 
REJECT__ERROR, SYSTEM_ ERROR, default] 
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Inbasket2__RetrieveEnvelopes 


NAME 


RetrieveEnvelopes - extract the envelope of a message 


SYNOPSIS 


#include <courier/Inbasket2 de.h> 
#include <courier/except.h> 


void 
RetrieveEnvelopes( Connection, BDTprocptr, index, whichMsg, session) 
COURIERFD Connection; ~ 
int(* BDTprocptr)(); 
LongCardinal index; 
T p18 2 69 whichMsg; 
Session session; 


DESCRIPTION 


The RetrieveEnvelopes() function is used to extract a particular message (envelope) from the inbasket. For 
messages of type StandardMessage, the heading (body part number 0) is also extracted. One message, a 
series of messages, or all the messages in the inbasket may be easily retrieved. 


The index argument is the index number of the message to be enumerated. The constant nulllndex may be 
used to enumerate all the messages in the inbasket. To enable nulllndex, whichMsg must be set to next. 
nulllndex is also returned when there are no more messages to enumerate. If there is no message in the 
inbasket that has the specified index value, IndexError is raised. 


The whichMsg argument is an enumerated type that determines which of two messages to enumerate. 
One of two values may be specified, this or next. this indicates that the message having the number 
specified in the index argument is to be enumerated. next indicates that the message after the message 
having the number specified in the index argument is to be enumerated. 


To view a series of messages, specify the index number of a message that immediately precedes the 
messages of interest and set whichMsg to next. After the first call to RetrieveEnvelopes(), set the value of 
index in the current call to the value of index returned by the previous call. This will cause all the 
messages starting from index+ 1 and ending with the last message to be enumerated. 


The session argument is the inbasket session handle returned by a preceding call to Logon(). 


RETURN VALUE 
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This function returns a structure called RetrieveEnvelopesResults. It has three members: 
transportEnvelope, status and index. 


transportEnvelope is of type Envelope.It is an array of records that defines the MTA-visible portions 
of the message. It contains information regarding the pre-delivery history of the message. 


status is of type Status. It is a structure that has two members: MessageStatus and BodyPartsStatus. 


MessageStatus is a structure that applies to the message as a whole. It indicates one of two 
conditions: NEW or KNOWN. NEW means the client has not yet been made aware of the delivery of 
the specific message. KNOWN means the client has been appraised of the delivery of the specific 
message but has not yet received the message contents. It is important to note that status serves as 
an indication of the reception of a message by the client, as mediated by the mail service. It does 
not reflect the delivery of the message itself to the client by the message transfer service, nor the 


DOCUMENT INTERFACES TOOLKIT SYSTEM REFERENCE 


XNS LIBRARY 


transfer of information to the inbasket. After being alerted as to the status of a message, it is the 
client’s responsibility to to update MessageStatus. 


BodyPartsStatus refers to, and indicates the condition of the sequence of component parts that 
comprise an entire message. BodyPartsStatus is an array of Boolean values, with one Boolean value 
per each message body part. The body parts of a message are numbered from zero to the actual number 
of body parts minus one. Body parts are numbered in the same order as they are displayed in 
tableOfContents. BodyPartindex is used to refer to a specific part of a message. 


index is a cardinal number that indicates the index number of the last enumerated message. When the 
value of index is nulllndex, it indicates that there are no more messages to enumerate. 


ERRORS 


Reports [AuthenticationError[problem], IndexError[problem], OtherError[problem], 
SessionError[problem], ServiceError[problem], Courier Errors: REJECT_ERROR, SYSTEM_ ERROR, 


default] 
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MailTransport5__AbortRetrieval 


NAME 


AbortRetrieval - postpone delivery of a message 


SYNOPSIS 


#include <courier/MailTran5 de.h> 
#include <courier/except.h> _ 


void 
AbortRetrieval( Connection, BDTprocptr, session) 
COURIERFD- Connection; — 


int(* BDTprocptr)(); 
Session session; 
DESCRIPTION 


The AbortRetrieval() function is used to direct the mail service to stop the retrieval process immediately 
and retain the remainder of the message until the client is ready to accept it. Subsequent messages will 
become unavailable until the envelope or message in question is disposed of in some way. This function 
may only be called immediately following a call to either RetrieveEnvelope() or RetrieveContent(). 


The session argument is the session handle returned by a preceding call to BeginRetrieval(). 


RETURN VALUE 


This function returns void. 


ERRORS 


Reports [AuthenticationError[problem], OtherError[problem], SessionError[problem], 
ServiceError[problem], TransferError[problem], Courier Errors: REJECT_ERROR, SYSTEM__ERROR, 
default] 
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MailTransport5 BeginPost 


NAME 


BeginPost - post outgoing messages 


SYNOPSIS 


#include <courier/MailTran5 de.h> 
#include <courier/except.h> _ 


BeginPostResults 
BeginPost( Connection, BDTprocptr, postingData, postifinvalidNames, allowDLRecipients, 
optionalEnvelopeData, credentials, verifier) 
COURIERFD Connection; 
int(* BDTprocptr)(); 
PostingData postingData; 
Boolean postlifinvalidNames; 
Boolean allowDLRecipients; 
T_p17 5 38 optionalEnvelopeData; 
Credentials credentials; 
Verifier verifier; 


DESCRIPTION 


The BeginPost() function is used to initiate the posting of a message with a mail service. Once an 
appropriate mail service has been located, BeginPost() is used to start the posting of a message. It is then 
followed by a sequence of PostOneBodyPart() operations, and terminated by EndPost(). 


The postingData argument is a structure that contains a list of clients to receive the message, the contents 
type, the size of the message contents, and a list of the body parts comprising the message. postingData 
contains four members: Recipients, contentsType, contentsSize, and bodyPartTypesSequence. 


Recipients is a sequence of records, each one defining the full path name of each intended recipient. 


contentsType is an enumerated type that directs the interpretation of messages by the Mail Service. 
One of the following values may be specified: 


UNSPECIFIED 
STANDARDMESSAGE 
REPORT 

NULL 


To be in a human readable format, the value of contentsType must be either REPORT or 
STANDARDMESSAGE. 


contentsSize specifies the size of the entire contents portion of the message in bytes. If the size 
specified is not within 5000 bytes of actual size, the Mail Service will raise an error. 


bodyPartTypesSequence is a sequence of body part types. Body part types for standard messages are a 
sequence of cardinal numbers that range between 0 and 12, inclusive. 0 indicates the Heading body 
part. Number 1-12 indicate portions of the Interpersonal Message body part. There should be a one-to- 
one correspondence between the body partsin T_r17_5__37 and the elements in the message. 


The postlfinvalidNames argument is a Boolean value that controls how BeginPost() handles invalid 
recipients. A value of TRUE causes all valid recipients to receive the message, regardless of the number of 
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non-valid recipients. The invalid recipient names will be returned. A value of FALSE will prevent the 
message from being sent to anyone if an invalid recipient name exists and an results in an error. 


The allowDLRecipients argument is a Boolean that indicates whether or not the message is to be sent to 
distribution lists. A value of TRUE causes the message to be sent regardless of the number of intended 
recipients. A value of FALSE causes any recipient that is a distribution list to be designated as invalid. 


The optionalEnvelopeData argument is a structure that allows the client to include additional 
information regarding the handling of the message. 


The credentials argument is the credentials returned earlier by the Authentication Service. The verifier 
argument is the verifier returned earlier by the Authentication Service. 


RETURN VALUE 
This function returns a structure called BeginPostResults. It has two members: session and invalidNames. 


session is of type Session. It is a mail transport session handle to be used to complete the posting 
process. 


invalidNames is of type InvalidNameList. It is a list of invalid recipients, in the case where not all the 
recipients are valid but the message was posted anyway. This can only occur when 
postifinvalidNames is set to TRUE. The mail transport session handle returned will be invalid if 
postifinvalidNames was set to FALSE and the recipient list contained invalid names. An error will be 
raised if an invalid mail transport session handle is passed to PostOneBodyPart(). 


ERRORS 


Reports [AuthenticationError[problem], InvalidRecipients[namelist], OtherError[problem], 
ServiceError[problem], Courier Errors: REJECT_ERROR, SYSTEM__ERROR, default] 
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MailTransport5__BeginRetrieval 


NAME 


BeginRetrieval - initiate the extraction of messages from a mail slot 


SYNOPSIS 


#include <courier/ MailTran5 de.h> 
#include <courier/except.h> _ 


BeginRetrievalResults 
BeginRetrieval( Connection, BDTprocptr, deliverySlot, credentials, verifier) 
COURIERFD Connection; — 
int(* BDTprocptr)(); 
ThreePartName deliverySlot; 
Credentials credentials; 
Verifier verifier; 


DESCRIPTION 


The BeginRetrieval() function is used to initiate the retrieval of one or more messages from a specified 
delivery slot. A typical delivery slot session consists of a call to BeginRetrieval(), multiple calls to 
RetrieveEnvelope() and RetrieveContent(), and a concluding call to EndRetrieval(). 


The deliverySlot argument identifies the slot to be accessed. A delivery slot is associated with a specific 
recipient name. To retrieve messages via a delivery slot, the client must locate the mail service on which 
the recipient name is registered. This is done by looking up the recipient’s name in the Clearinghouse to 
determine the value of the mailboxes property associated with that name. (The format of this property is 
defined in the Clearinghouse Entry Formats Standard.) The mailboxes property contains an array of mail 
service names, each of which hold a mailbox for the user. 


The credentials argument is the credentials returned earlier by the Authentication Service. The 
credentials may be either simple or strong. If the delivery slot is not owned by the client identified in the 
credentials, the client must have strong credentials to access that slot. The client cannot switch from 
simple to strong authentication or visa versa within the same session. 


The verifier argument is the simple verifier acquired at the same time as the credentials. 


RETURN VALUE 


This function returns a structure called BeginRetrievalResults. Its one member, session, is of type Session. 
It is the mail transport session handle that is to be passed to all related *Retrieval() functions. 


ERRORS 


Reports [AccessError[problem], AuthenticationError[problem], OtherError[problem], 
ServiceError[problem], Courier Errors: REJECT_ERROR, SYSTEM_ ERROR, default] 
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MailTransport5__EndPost 


NAME 


EndPost - signal termination of posting a message 


SYNOPSIS 


#include <courier/MailTran5 de.h> 
#include <courier/except.h> _ 


EndPostResults | 
EndPost( Connection, BDTprocptr, session, abortPost) 
COURTERFD Connection; 
int(* BDTprocptr)(); 
Session session; 
Boolean abortPost; 


DESCRIPTION 


The EndPost() function is used to signal the mail service that the message initiated by BeginPost() is 
complete and no more data is to follow. 


The session argument is the transport session handle returned by BeginPost(). Once the call to EndPost() 
completes, the mail transport session handle is no longer valid. The abortPost argument is a Boolean that 
indicates what is to be done with the completed message. If abortPost is TRUE, the message will not be 
posted and it will be discarded by the mail service. If set to FALSE, the message will be sent to the 
recipients listed in BeginPost(). The default is FALSE. 


RETURN VALUE 


This function returns a structure of type EndPostResults. Its one member, messagelD, is of type 
MessagelD. messagelD is a unique identifier assigned by the mail service during posting and is used for 
use in pairing messages to their associated reports or in locating messages referenced by other messages. 


ERRORS 


Reports [AuthenticationError[problem], OtherError[problem], SessionError[problem], 
ServiceError[problem], TransferError[problem], Courier Error] 
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MailTransport5__EndRetrieval 


NAME 


EndRetrieval - terminate a retrieval sequence 


SYNOPSIS 


#include <courier/MailTran5 de.h> 
#include <courier/except.h> 


void 
EndRetrieval( Connection, BDTprocptr, session) 
COURIERFD Connection; 
int(* BDTprocptr)(); 
Session session; 
DESCRIPTION 
The EndRetrieval() function is used to end the current delivery slot retrieval sequence. Calling this 
function invalidates the session handle returned by a preceding call to BeginRetrieval(). 
The session argument is the session handle returned by a preceding call to BeginRetrieval(). 


RETURN VALUE 


This function returns void. 


ERRORS 


Reports [AuthenticationError[problem], OtherError[problem], SessionError[problem], 
ServiceError[problem], TransferError[problem], Courier Errors: REJECT_ERROR, SYSTEM__ERROR, 
default] 


DOCUMENT INTERFACES TOOLKIT SYSTEM REFERENCE 8-83 


XNS LIBRARY 


MailTransport5__MailPoll 


NAME 


MailPoll - check a delivery slot for messages 


SYNOPSIS 


#include <courier/ MailTranS5 de.h> 
#include <courier/except.h> _ 


MailPollResults 
MailPoll( Connection, BDTprocptr, deliverySlot, credentials, verifier) 
COURTERFD Connection; | 
int(* BDTprocptr)(); 
ThreePartName deliverySlot; 
Credentials credentials; 
Verifier verifier; 


DESCRIPTION 


The MailPoll() function is used to determine if messages are present in a delivery mail slot. Due to the 
overhead of invoking the various *Retrieval() functions, MailPoll() is the suggested means of verifying the 
existence of mail. 


The deliverySlot argument identifies the slot to be accessed. A delivery slot is associated with a specific 
recipient name. To retrieve messages via a delivery slot, the client must locate the mail service on which 
the recipient name is registered. This is done by looking up the recipient’s name in the Clearinghouse to 
determine the value of the mailboxes property associated with that name. (The format of this property is 
defined in the Clearinghouse Entry Formats Standard.) The mailboxes property contains an array of mail 
service names, each of which may contain mail for the specified recipient. 


The credentials argument is the credentials returned earlier by the Authentication Service. The 
credentials may be either simple or strong. If the delivery slot is not owned by the client identified in the 
credentials, the client must have strong credentials to access that slot. The client cannot switch from 
simple to strong authentication or visa versa within the same session. 


The verifier argument is the simple verifier acquired at the same time as the credentials . 


RETURN VALUE 


This function returns a structure called MailPollResults. Its one member, mailPresent, is a Boolean value 
that indicates the presence of mail in the delivery slot. A value of TRUE indicates there is mail ready for 
retrieval. A value of FALSE indicates that the delivery slot is empty. 


ERRORS 


8-84 


Reports [AccessError[problem], AuthenticationError[problem], OtherError[problem], 
SessionError[problem], ServiceError[problem], Courier Errors: REJECT_ERROR, SYSTEM__ERROR, 
default] 
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MailTransport5__PostOneBodyPart 


NAME 


PostOneBodyPart - send message data to a mail service 


SYNOPSIS 


#include <courier/MailTranS de.h> 
#include <courier/except.h> 


void 
PostOneBodyPart( Connection, BDTprocptr, session, bodyPartType, contents) 
COURIERFD Connection; ~ 
int(* BDTprocptr)(); 
Session session; 
LongCardinal bodyPartType; 
BulkData1 Descriptor contents; 


DESCRIPTION 


The PostOneBodyPart() function is used to submit the data that was declared in BeginPost() to a mail 
service. BeginPost() informs the mail service that a specific body of data, having specific qualities, is to 
follow. PostOneBodyPart() specifies that body of data. This function is to be called once for each body part. 
If more than five minutes elapses between the time BeginPost() is called and PostOneBodyPart() is called, 
an error is raised. 


The BDTprocptr argument is the name of the client-defined function that will be posting the body part. 
This function must be provided. 


The session argument is the transport session handle returned by BeginPost(). The bodyPartType 
argument is a cardinal number that indicates the body part. This argument insures that all the body parts 
that are supposed to be included in the message are sent to the mail service. The value of this argument is 
to be identical with the value of bodyPartTypeSequence that was specified in BeginPost(). If there is any 
discrepancy between BeginPost(), bodyPartTypeSequence, and bodyPartType, an error is raised. 


The contents argument specifies the source that is to supply the data comprising the message in 
accordance to the Bulk Data Transfer Protocol. 


RETURN VALUE 


This function returns void. 


ERRORS 


Reports [AuthenticationError[problem], OtherError[problem], SessionError[problem], 
ServiceError[problem], TransferError[problem], Courier Errors: REJECT_ERROR, SYSTEM __ERROR, 
default] 
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MailTransport5__RetrieveContent 


NAME 


RetrieveContent - extract the contents of a message 


SYNOPSIS 


#include <courier/MailTranS5 de.h> 
#include <courier/except.h> | 


void 
RetrieveContent( Connection, BDTprocptr, content, session) 
COURIERFD “Connection; ~ 
int(* BDTprocptr)(); 
BulkData1 Descriptor content; 
Session session; 
DESCRIPTION 
The RetrieveContent() function is used to extract the contents of a message that is at the head of the 
delivery slot queue. This function must follow a successful call to RetrieveEnvelope(). 


The _BDTprocptr argument is the name of the client-defined function that will retrieve the contents of the 
message. This function must be provided. 


The content argument is the sink that is to receive the contents in accordance to the Bulk Data Transfer 
Protocol. Use BulkDatal__immediateSink when retrieving to a local file. 


The session argument is the session handle returned by a preceding call to BeginRetrieval(). 


RETURN VALUE 


This function returns void. 


ERRORS 


Reports [AuthenticationError[problem], OtherError[problem], SessionError[problem], 
ServiceError[problem], TransferError[problem], Courier Errors: REJECT_ERROR, SYSTEM_ ERROR, 
default] : 
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MailTransport5 RetrieveEnvelope 


NAME 


RetrieveEnvelope - extract the header information regarding a delivery slot message 


SYNOPSIS 


#include <courier/MailTran5 de.h> 
#include <courier/except.h> 


RetrieveEnvelopeResults 

RetrieveEnvelope( Connection, BDTprocptr, session) 
COURIERFD Connection; ~~ 
int(* BDTprocptr)(); 
Session session; 


DESCRIPTION 


The RetrieveEnvelope() function is used to extract an envelope from the head of the delivery slot queue 
and, for those messages with contents of type ctStandardMessage, the heading (body part #0) is also 
extracted. The extracted envelope does not contain the message itself, only pertinent information 
regarding the message. If, based upon the envelope information, the message is of no interest, the 
envelope contents may be discarded by immediately calling RetrieveEnvelope() a second time. 


This function may be called repeatedly in tandem with RetrieveContent() during the same session to 
extract all the envelopes in a delivery slot. 


The session argument is the session handle returned by a previous call to BeginRetrieval(). 


RETURN VALUE 


This function returns a structure called RetrieveEnvelopeResults. It has two members: empty and 
envelope. 


empty is a Boolean value that indicates the presence of available envelopes. A value of TRUE indicates 
that the active delivery slot is empty and there are no envelopes. A value of FALSE indicates that the 
delivery slot is not empty and there are envelopes available. 


envelope is of type Envelope. It is the envelope itself. 


ERRORS 


Reports [AuthenticationError[problem], OtherError[problem], SessionError[problem], 
ServiceError[problem], TransferError[problem], Courier Errors: REJECT_ERROR, SYSTEM__ERROR, 
default] 
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MailTransport5_ServerPoli 


NAME 


ServerPoll - query the mail service if it will accept posted messages 


_ SYNOPSIS 


#include <courier/MailTranS de.h> 
#include <courier/except.h> _ 


ServerPollResults 

ServerPoll( Connection, BDTprocptr) 
COURIERFD Connection; 
int (* _BDTprocptr)() : 


DESCRIPTION 


The ServerPoll() function is used to determine if the mail service currently in use will accept additional 
messages for posting. This function may be broadcast to assist other clients in locating a mail service to 
use for posting messages. This function requires only the _Connectionand _ BDTprocptr arguments. 


RETURN VALUE 


This function returns a structure called ServerPollResults. It has three members: willingness, address, 
and serverName. 


willingness is of type Willingness. It is a cardinal number that specifies the availability of a particular 
mail service for posting mail. The range of willingness is between 1 and 10, inclusive. 1 is least 
receptive to new postings. 10 is most receptive. The returned value for willingness[i] gives the 
service’s ability to accept messages of size 8[i] bytes to size (8[i+ 1] - 1) bytes. The last element in the 
sequence gives the service’s ability to accept a message of size 8(index of the last element in the 
sequence) bytes to a message of unbounded size, 


address is of type NetworkAddressList. It is the list of clearinghouse network addresses that may be 
used to contact a mail service. The address list will contain more than one element only if the mail 
service is connected to more than one network. 


serverName is of type ThreePartName. It is a full path name that identifies the name of the responding 
mail service. 


ERRORS 
Reports [Courier Errors: REJECT_ERROR, SYSTEM__ERROR, default] 
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Printing3__GetPrinterProperties 


NAME 


GetPrinterProperties - retrieve the static properties of a printer 


SYNOPSIS 


#include <courier/Printing3 de.h> 
#include <courier/except.h>_ 
#include <courier/ papersize.h> 


GetPrinterPropertiesResults 
GetPrinterProperties( Connection, BDTprocptr) 
COURIERFD Connection; _ 
int(* _BDTprocptr)(); 


DESCRIPTION 


The GetPrinterProperties() function is used to query the print service for the static properties of a printer. 
This function knows the printer to access based upon the value of the __Connection argument. 


RETURN VALUE 


This function returns a structure called GetPrinterPropertiesResults. Its one member, properties, specifies 


the handling characteristics of the printer. properties is of type PrinterProperties. It has three fields: 
media, staple, and twoSided. 


The media field is like the mediumHint parameter of PrintOptions in that it specifies the paper sizes 
available for a specific printer. The media listed need not be immediately available, but the print 
service should be able to provide them at the time of printing. 


The staple field specifies if a document sent to the printer in question will be stapled upon completion. 
The default is FALSE. 


The twoSided argument specifies whether or not a document will be printed on both sides of each 
sheet of paper. The default is FALSE. 


ERRORS 
Reports [ServiceUnavailable, SystemError, Undefined[problem]] 


SEE ALSO 
Print() 
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Printing3__GetPrinterStatus 


NAME 


GetPrinterStatus - determine the availability of the print service 


SYNOPSIS 


#include <courier/Printing3 de.h> 
#include <courier/except.h>- 
#include <courier/papersize.h> 


GetPrinterStatusResults 

GetPrinterStatus( Connection, BDTprocptr) 
COURIERFD Connection; ~~ 
int(* BDTprocptr)(); 


DESCRIPTION 


The GetPrinterStatus() function is used to determine where the print service is with respect to the four 

aspects of printing a document: spooling, formatting, printing, and the paper on which to print the 

document. The spooler accepts a master; the formatter decomposes it; and the printer marks the 

decomposed document for printing. This function knows the printer to access based upon the value of the 
Connection argument. 


RETURN VALUE 


The GetPrinterStatus() function returns GetPrinterStatusResults. Its one member, status, describes the 
state, or condition, of the four aspects of printing. status is of type PrinterStatus. It contains the status of 
four objects: spooler, formatter, printer, and media. 
The spooler may be in any one of four states: AVAILABLE, BUSY, DISABLED, and FULL. 
- The formatter may be in any one of three states: AVAILABLE, BUSY, and DISABLED. 


The printer may be in any one of five states: AVAILABLE, BUSY, DISABLED, NEEDSATTENTION, and 
NEEDSKEY OPERATOR. 


And MEDIA describes the paper sizes that are available on the printer. 


AVAILABLE indicates that the respective phase is ready to accept input. 


BUSY indicates that the respective phase is currently processing another print request and cannot 
accept input. This is a transient condition that lasts a relatively short time. 


DISABLED indicates that the respective phase is not available and cannot accept input. The 
duration of this state may last a long time. 


FULL indicates that the spooler is currently unable to accept additional input. This is due to the 
number of printing requests exceeding the capacity of the spooler queue. 


NEEDSATTENTION indicates that the marking engine of the printer is not functioning properly 
and requires some non-technical human intervention. 


NEEDSKEYOPERATOR indicates that the marking engine of the printer is not functioning properly 
and requires the attention of a trained technician. 


MEDIA enumerates the paper sizes currently available on the target printer. 
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ERRORS 


Reports [ServiceUnavailable, SystemError, Undefined] 


SEE ALSO 
Print(), GetPrintRequestStatus(), GetPrinterProperties() 
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Printing3__GetPrintRequestStatus 


NAME 


GetPrintRequestStatus - determine the status of an outstanding print request 


SYNOPSIS 


#include <courier/Printing3 de.h> 
#include <courier/except.h> 
#include <courier/ papersize.h> 


GetPrintRequestStatusResults 
GetPrintRequestStatus(_ Connection, _BDTprocptr, printRequestiD) 


COURIERFD Connection; 
int(* BDTprocptr)(); 
RequestiD printRequestiD; 


DESCRIPTION 


The GetPrintRequestStatus() function is used to ascertain the status of a document that was sent to a 
printer. The printRequestID argument is the return value of the Print() function and must be supplied here 
to properly identify the document in question. 


RETURN VALUE 


This function returns a structure called GetPrintRequestStatusResults. Its one member, status, is of type 
RequestStatus. It may have one of the following nine values: 


PENDING, has not begun printing. 

INPROGRESS, currently being printed. 

COMPLETED, the document has successfully completed printing. 

COMPLETEDWITHWARNING, the document has been printed but low level problems have been 
encountered. 

UNKNOWN, the print service is at a complete loss as to what happened to the document in question. 
REJECTED, the document was not accepted into the marking phase because errors, such as illegal 
interpress commands, have been encountered in the master. 

ABORTED, the printing request was aborted during the formatting or marking phase. 

CANCELLED, the document was queued for printing but someone having priority credentials cancelled 
the printing request. 

HELD, the printing service has postponed processing the document until a later time because other 
print requests having a higher priority have been received. 


ERRORS 


Reports [ServiceUnavailable, SystemError, Undefined[problem]] 


SEE ALSO 
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Print(), GetPrinterProperties(), GetPrinterStatus() 
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Printing3__Print 


NAME 


Print - print a master 


SYNOPSIS 


#include <courier/Printing3 de.h> 
#include <courier/except.h> 
#include <courier/papersize.h > 


PrintResults 
Print( Connection, BDTprocptr, master, printAttributes, printOptions) 
COURIERFD Connection; 
int(* BDTprocptr)(); 
BulkData1 Descriptor master; 
PrintAttributes printAttributes; 
PrintOptions printOptions; 


DESCRIPTION 


The Print() function is used to access bulk transfer data in a source and send it to the print service queue. 
This function knows the printer to access based upon the value ofthe _ Connection argument. 


The _BDTprocptr argument is the name of the client defined function that will send the data to the print 
queue. This function must be provided. 


The master argument is a bulk data transfer parameter that specifies the source that is to supply the 
interpress master in accordance with the Bulk Data Transfer Protocol. Use BulkDatal__immediateSink 
when retrieving to a local file. 


The printAttributes argument is a structure that specifies supplementary information about the document 
to be printed, such as the name of the object to be printed, the creation date, and the sender's name. The 
information specified here is printed on the document cover page. 


The printOptions argument specifies parameters that affect the printing of a document, and the 
characteristics the printed document is to have or that are relevant to the printing process. There are ten 
parameters to this argument: 


The first, printObjectSize, indicates the size of the master to be printed in bytes. This may be useful for 
allocating printing resources or determining if the master size exceeds the capability of the printer. 
The default value is the size of the master received. 


The second parameter, recipientName, is the name of the person for whom the printed document is 
intended. Typically this will appear on the banner sheet of the printed document and, on print servers 
with sorters, it may be used as the basis of a sort key. The default value is the same as the senderName 
parameter specified in the printAttributes argument. 


The message parameter is typically used to specify the status information to be displayed either 
locally or printed on the banner sheet. This message accompanies a print request. It is a text string. 
The default is a NULL string. 


The copyCount parameter specifies the number of copies to be made. The default is 1. 


The pagesToPrint parameter specifies the range of pages to be printed. beginningPageNumber 
specifies the page number at which printing is to commence. 
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The endingPageNumber parameter specifies the page number at which printing is to stop. "Page 
number" is the ordinal position of the page in the document, not the page number actually printed on 
the page. The default value is every page in the master. 


The mediumHint parameter indicates the size of the paper on which the document is to be printed. 
Refer to papersize.h and Printing3.cr for information regarding acceptable paper sizes and the format 
for specifying them. Though listed as an option, the value of unknown may not be used. The default 
paper size is specific to each print service. 


The priorityHint parameter is the printing priority requested by the sender. The default value is 
specific to each print service. If a request is not to be processed immediately by the print service a non- 
NULL releaseKey is to be supplied by the user. 


The releaseKey parameter is datum that must be presented to the print service in order to release a 
held request. The source for a releaseKey is assumed to be a password consisting of a string of 
characters. The releaseKey is computed from the password using the algorithm specified by the 
Authentication Protocol. The default value is 177777B, ”NULL string”. 


The staple parameter specifies if the document is to be stapled upon completion. The default is FALSE. 


The twoSided parameter specifies whether or not the document is to be printed on both sides of each 
sheet of paper. The default is FALSE. 


RETURN VALUE 


This function returns PrintResults, a structure whose one member, printRequestiID, contains a unique 
identifier for the document being printed. The identifier is assigned by the print service and is of type 
RequestiD. It may later be supplied as an argument to GetPrintRequestStatus(), a function that ascertains 
the status of documents that have been sent to the print spooler. 


ERRORS 


Reports [Busy, ConnectionError, InsufficientSpoolSpace, InvalidPrintParameters, MasterTooLarge, 
MediumUnavailable, ServiceUnavailable, SpoolingDisabled, SpoolingQueueF ull, SystemError, 
TooManyClients, TransferError[problem], Undefined[problem]] 


SEE ALSO 


GetPrintRequestStatus(), GetPrinterProperties(), GetPrinterStatus() 
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_ BDTProcPtr, 8-2 
_ Connection, 8-1 


A 
Authentication2__ChangeSimpleKey, 8-5 
Authentication2__ChangeStrongKey, 8-5 
Authentication2__CheckSimpleCredentials, 8-7 
Authentication2__CreateSimpleKey, 8-8 
Authentication2__CreateStrongKey, 8-8 
Authentication2__DeleteSimpleKey, 8-10 
Authentication2__DeleteStrongKey, 8-10 
Authentication2__GetStrongCredentials, 8-11 
anchored frame 

start creation, see gi__startgr 
auxiliary menus, see document 


B 

bar chart, see gi__adbacht 

bit map graphics, see gi__adbm 
brush widths, 3-33 


C 

call-back procedures 
di__aframeproc, 1-30 
di__apfstyleproc, 1-52 
di__appstyleproc, 1-52 
di__breakproc, 1-30 
di__ckabortproc, 1-38 
di__docproc, 1-30 
di__fieldproc, 1-31 
di__fillinproc, 1-34 
di__fnpropsproc, 1-41 
di__fntileproc, 1-31 
di_fstyleproc, 1-35 
di__indexproc, 1-31 
di__newparaproc, 1-31 
di__pfcproc, 1-31 
di__pstyleproc, 1-35 
di__sfbrkproc, 1-31 
di__styleproc, 1-52 
di__textproc, 1-31 
di__txtInkproc, 1-37 
gi__bachtproc, 3-55 
gi__bmproc, 3-55 
gi__buttonproc, 3-55 
gi__clusterproc, 3-55 
gi__curveproc, 3-55 
gi__ellipseproc, 3-56 
gi__ffieldproc, 3-56 
gi_frameproc, 3-56 
gi_lineproc, 3-56 
gi_Inchtproc, 3-56 
gi__pichtproc, 3-56 
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gi__pislceproc, 3-56 

gi__pointproc, 3-57 

gi__rectangleproc, 3-57 

gi__tableproc, 3-57 

gi__tframeproc, 3-57 

gi__triangleproc, 3-57 

ti_columnproc, 4-12 

ti_rowproc, 4-12 

ti_tableproc, 4-12 
Clearinghouse2__AddGroupProperty, 8-13 
Clearinghouse2__AddltemProperty, 8-15 
Clearinghouse2__AddMember, 8-17 
Clearinghouse2__AddSelf, 8-17 
Clearinghouse2__Changeltem, 8-19 
Clearinghouse2__CreateAlias, 8-20 
Clearinghouse2__CreateObject, 8-22 
Clearinghouse2__DeleteAlias, 8-20 
Clearinghouse2__DeleteMember, 8-23 
Clearinghouse2__DeleteObject, 8-25 
Clearinghouse2__DeleteProperty, 8-26 
Clearinghouse2__DeleteSelf, 8-23 
Clearinghouse2__IsMember, 8-27 
Clearinghouse2__ListAliases, 8-20 
Clearinghouse2__ListAliasesOf, 8-29 
Clearinghouse2__ListDomain, 8-30 
Clearinghouse2__ListDomainServed, 8-31 
Clearinghouse2__ListObjects, 8-32 
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CUSP button 

ancored frame properties, see gi__btnforaframe 

create, see gi__startnbtn 

enumerate contents, see gi__enumbtnprog 

release handles, see gi__relbtnprog 


D 

data types 
DocIC, 1-2 

desktop 
access permissions, see dsktp__getaccess 
copy document, see dsktp__copydoc 
delete folder, see dsktp__deletefolder 
document handle, see dsktp__getdocref 
list folder contents, see dsktp__enumerate 
make folder, see dsktp__makefolder 
overview, 5-1 
properties, see dsktp__getdocprops 
remove document, see dsktp__deletedoc 
security/access control, see dsktp__checkuser 


INDEX-1 


INDEX 


di__abort(), 1-5 
di__apaframe(), 1-6 
di__apaframe, 1-6 
di__apbreak, 1-9 
di__apchar, 1-10 
di__apfield, 1-11 
di__apfntile, 1-13 
di__apfstyle, 1-14 
di__apindex, 1-16 
di__apnewpara, 1-18 
di__appfc, 1-20 
di__appstyle, 1-14 
di__aptext, 1-22 
di__aptofillin, 1-24 
di__aptotxtInk, 1-25 
di__clearfillin, 1-27 
di__cleartxtInk, 1-28 
di_close, 1-29 
di__enumerate, 1-30 
di__enumfillin, 1-34 
di_enumstyle, 1-35 
di__enumtxtInk, 1-37 
di__fillintype, 1-24 
di__finish, 1-38 
di__getfieldfromname, 1-40 
di_getfnprops, 1-41 
di__getmode, 1-49 
di_open, 1-43 
di_rel*, 1-45 
di__setfnprops, 1-47 
di__setmode, 1-49 
di__setpara, 1-50 
di__start, 1-52 
di__startap, 1-55 
di__starttext, 1-57 
di__tcont 


new paragraph characters, 1-18 


di__textforaframe, 1-58 
document 
creation, 1-1 
enumeration, 1-1 
properties 
anchored frame, 2-7 
basic records, 2-13 
break, 2-1 
color, 2-18 
dp__fontdesc, 2-5 
dp__fontprops, 2-6 
field, 2-1 | 
font, 2-5 
font runs, 2-2 
font style, 2-15 
footnote numbering, 2-3 
index, 2-9 
mode, 2-15 
page, 2-9 
paragraph, 2-12 
paragraph style, 2-16 
tab, 2-14 
textframe, 2-17 
dp__colfromname, 2-20 
dp__enumfrun, 2-22 
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dp__getbaspropsdef, 2-25 
dp__getbreakdef, 2-24 
dp__getcolwidthdef, 2-24 
dp__getfielddef, 2-24 
dp__getfnnumdef, 2-24 
dp__getfontdef, 2-24 
dp__getfontdescdef, 2-24 
dp__getfontelmarralltrue, 2-25 
dp__getfontstyledef, 2-25 
dp__getframedef, 2-24 
dp__getindexdef, 2-24 
dp__getmodedef, 2-25 
dp__getpagedef, 2-24 
dp__getpagedel, 2-25 
dp__getparadef, 2-24 
dp__getparaelmarralltrue, 2-25 
dp__getparastyledef, 2-25 
dp__getrundef, 2-24 
dp__gettabstopdef, 2-25 
dp__gettframedef, 2-25 
dp__gettoc, 2-25 
dp__namefromcol, 2-20 
dp__pageprops 

set margins, 1-20 
dp__wkcolfromcol, 2-20 
dsktp__checkuser, 5-2 
dsktp__copydoc, 5-3 
dsktp__deletedoc, 5-5 
dsktp__deletefolder, 5-13 
dsktp__docref, 1-38 
dsktp__enumerate, 5-6 
dsktp__getaccess, 5-8 
dsktp__getdocprops, 5-9 
dsktp__getdocref, 5-11 
dsktp__intro, 5-1 
dsktp__makefolder, 5-13 
dsktp__movedoc, 5-15 


E 
eccentricity, 3-19 
enumeration 
fill-in runs, 2-22 
graphics container, 3-2 


F 
Filing6__ChangeAttributes, 8-47 
Filingé__ChangeControls, 8-49 
Filing6__Close, 8-39 
Filing6__Continue, 8-40 
Filing6__Copy, 8-41 
Filing6__Create, 8-42 

Filing6_ Delete, 8-44 
Filing6__Deserialize, 8-61 
Filing6__Find, 8-45 
Filing6__GetAttributes, 8-47 
Filing6__GetControls, 8-49 
Filing6__List, 8-50 

Filing6__ Logoff, 8-52 
Filing6__Logon, 8-53 
Filing6__Move, 8-54 

Filing6_ Open, 8-55 
Filing6__Replace, 8-57 
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Filing6__ReplaceBytes, 8-59 
Filing6__Retrieve, 8-58 
Filing6__RetrieveBytes, 8-59 
Filing6__Serialize, 8-61 
Filing6__ Store, 8-63 
Filing6__UnifyAccessLists, 8-64 
font families, 2-5 

frame contents, 1-1 


G 

Gap3, 8-65 

getsigno, 7-1 

gi_intro, 3-1 

gi__adbacht, 3-5 
gi_adbm, 3-11 
gi__adcurve, 3-16 
gi__adellipse, 3-21 
gi__adffield, 3-25 
gi__adline, 3 -28 
gi__adIncht, 3-30 
gi__adpicht, 3-33 
gi__adpislce, 3-35 
gi__adpoint, 3 -38 
gi__adrectangle, 3 -40 
gi__adtable, 3-43 
gi_adtframe, 3-45 
gi__adtriangle, 3-47 
gi__apchartobtnprog, 3-50 
gi__apnparatobtnprog, 3-50 
gi__aptexttobtnprog, 3-50 
gi__btnforaframe, 3-52 
gi_enumbtnprog, 3-53 
gi__enumerate, 3-55 
gi__finishbtn, 3-71 
gi__finishcht, 3 -59 
gi__finishcluster, 3 -59 
gi__finishgframe, 3 -59 
gi__finishgr, 3-59 
gi__finishnbtn, 3-59 
gi__getbachtpropsdef, 3-62 
gi__getbmdispdef, 3-62 
gi__getbmpropsdef, 3-62 
gi__getbmscalpropsdef, 3-62 
gi__getboxdef, 3-62 
gi__getchtappdef, 3-62 
gi__getchtdatdef, 3-62 
gi__getcurvepropsdef, 3-62 
gi__getellipsepropsdef, 3-62 
gi__getframepropsdef, 3-62 
gi__getgframepropsdef, 3-62 
gi__getgridpropsdef, 3-62 
gi__getlinepropsdef, 3-63 
gi__getInchtappdef, 3-63 
gi__getInchtpropsdef, 3-63 
gi__getpichtpropsdef, 3-63 
gi__getpislcepropsdef, 3-63 
gi__getpointpropsdef, 3-63 
gi__getrectanglepropsdef, 3-63 
gi__gettframepropsdef, 3-63 
gi__gettrianglepropsdef, 3-63 
gi__getgframeprops, 3-61 
gi__relbtnprog, 3-68 
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gi_setgframeprops, 3-69 
gi__startbtn, 3-71 
gi__startcluster, 3-73 
gi__startgframe, 3-75 
gi__startgr, 3-79 
gi__startnbtn, 3-80 
graphics 
clusters, 3-73 
create, 3-1 
cross-reference, 3-2 
read, 3-1 
graphics frame 
create, see gi__startgframe 
enumerate contents, see gi__enumerate 
enumerate properties, see gi__getgframeprops 
set properties, see gi__setgframeprops 


H 


I 

Inbasket2__ChangeBodyPartsStatus, 8-67 
Inbasket2__ChangeMessageStatus, 8-68 
Inbasket2__Delete, 8-69 
Inbasket2__GetSize, 8-70 
Inbasket2__Logoff, 8-71 
Inbasket2__Logon, 8-71 
Inbasket2__MailCheck, 8-73 
Inbasket2__MailPoll, 8-74 
Inbasket2__RetrieveBodyParts, 8-75 
Inbasket2__RetrieveEnvelopes, 8-76 


J 
K 


L 

line 
properties, see gi__lineprops 
chart, 3-30 


M 
mail services, see Mai/Transport5__* 
MailTransport5__AbortRetrieval, 8-78 
MailTransport5__BeginPost, 8-79 
MailTransport5__BeginRetrieval, 8-81 
MailTransport5__EndPost, 8-82 
MailTransport5__EndRetrieval, 8-83 
MailTransport5__MailPoll, 8-84 
MailTransport5__PostOneBodyPart, 8-85 
MailTransport5__RetrieveContent, 8-86 
MailTransport5__RetrieveEnvelope, 8-87 
MailTransport5__ServerPoll, 8-88 
messages 

access, see Inbasket2__Logoff, Inbasket2__Logon 

delete, see Inbasket2__Delete 

body parts, see Inbasket2__ChangeBodyParts, 

Inbasket2__RetrieveBodyParts 

envelope, see /nbasket2__RetrieveEnvelopes, 

size, see Inbasket2__GetSize 

status, see Inbasket2__ChangeMessageStatus, 

Inbasket2__Mai!lCheck, Inbasket2__MailPoll 
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N 
nested frame, 3-1 


O 


P 
pagination, 1-52 
paragraph characters 
add to CUSP button, see gi__ap*btnprog 
insert, 1-3, 1-50 
pie chart 
join elements, 3-34 
placement, 3-33 
pie slice 
placement, 3-36 
texture, 3-36 
point 
placement, 3-38 
printer 
properties, see Printing3__GetPrinerProperties 
status, see Printing3__GetPrinterStatus, 
Printing3__GetPrintRequestStatus 
print, see Printing3__Print 
printing 
bit map graphics, 3-14 
print, see Printing3__Print 
Printing3__GetPrinterProperties, 8-89 
Printing3__GetPrinterStatus, 8-90 
Printing3__GetPrintRequestStatus, 8-92 
Printing3__Print, 8-93 


Q 


R 

rectangle, see gi__adrectangle 

release functions 
di__finish, 1-53 
di__relcap, 1-45 
di__relfield, 1-45 
di_relfoot, 1-45 
di_relhead, 1-45 
di_relnum, 1-45 
di__relindex, 1-45 © 
di__reltext, 1-45 


S 

signals 
getsigno, 7-1 

status 
di__opstat, 1-43 
di__scstat, 1-54, 1-55 
dsktp__docref, 1-38 


T 
tabs 
alignment, 2-14, 2-15 
settings, 2-14 
tables 
add rows, see gi__appendrow 
build, 4-1 
create new, see ti__starttable 
default font properties, see ti_deffont 
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default paragraph properties, see ti__defpara 
default properties, see ti_get*def 
edit existing, see ti__startextable 
enumerate contents, see ti_enumtable 
estimate number of cells, see ti_.maxelm 
extract properties, see ti__gettableprops 
finish, see ti__finishtable 
placement, 3-43 
properties 
basic, 4-2 
column, 4-4 
column header, 4-5 
other column properties, 4-8 
row contents, 4-8 
read, 4-2 
terminal emulation, see Gap3__Create 
text 
add to CUSP button, see gi__ap*btnprog 
inner margin, see dp__tframeprops 
orientation, see dp__tframeprops 
text frame, see gi__adtframe 
ti_appendrow, 4-10 
ti__deffont, 4-11 
ti_defpara, 4-11 
ti__enumtable, 4-12 
ti__finishtable, 4-14 
ti_get*def, 4-15 
ti_getlinedef, 4-15 
ti__getsortkeydef, 4-15 
ti__getcolinforecdef, 4-15 
ti_gethdentrydef, 4-15 
ti_getrowentdef, 4-15 
ti_gettableprops, 4-17 
ti_gettablepropsdef, 4-15 
ti_intro, 4-1 
ti_maxelm, 4-18 
ti__startextable, 4-19 
ti__starttable, 4-21 
triangle, see gi__adtriangle 


U 
Vv 
WwW 


X 
XCCS 
page number delimeter, see dp__getpagedel 
table of contents characters, see dp__gettoc 
XCharcode, 6-3 
XCharmake, 6-3 
XCharset, 6-3 
XNS 
__BDTProcPtr 8-2 
_Connection 8-1 
aliases, see CreateAlias, DeleteAlias, ListAliases, 
ListAliasesOf 
error handling, 8-3 
header files, 8-4 
change key, see ChangeStrongKey, 
ChangeSimpleKey 
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create key, see CreateStrongKey, 
CreateSimpleKey 

credentials, see CheckSimpleCredentials, 
GetStrongCredentials, 

delete key, see DeleteStrongKey, 
DeleteSimpleKey 

domains, see ListDomain, ListDomainsServed 

group properties, see AddGroupProperty 

file 
access, see GetControls, ChangeControls, 

UnifyAccessLists 


attributes, see GetAttributes, ChangeAttributes 
contents, see Replace, Retrieve, RetrieveBytes, 


ReplaceBytes 
create, see Create, Store 
delete, see Delete 
duplicate, see Copy 
encode, see Serialize, Deserialize 
handle, see Close, Open 
list, see List 
locate, see Find 
move, see Move 
item properties, see Add/temProperty, 
Changeltem 
logoff, see Logoff 
logon, see Logon 
members, see AddMember, DeleteMember, 
IsMember 
network, see RetrieveAddresses 
objects, see CreateObject, DeleteObject, 


DeleteProperties, ListObjects, ListProperties 
LookupObject, Retrieveltem, RetrieveMembers 


organizations, see ListOrganizations, 
XStrcasecmp, 6-6 
XStrcaselexcmp, 6-10 
XStrcat, 6-5 
XStrcmp, 6-6 
XStrcpy, 6-8 
XStrdup, 6-8 
XString 
append string, see XStrcat, XStrncat 
character code, see XCharcode 
character set, see XCharset 
compare, see XStrcmp, XStrncmp, 
XStrcasecmp, XStrncasecmp 
convert, see XStrfromASC, XStrtoASC, 
XStrfromXCC8, XStrtoXCC8 
copy, see XStrcpy, XStrncpy, XStrdup 
create, see XCharmake 
length, see XStrlen 
search, see XStrchr, XStrrchr, XStrpbrk, 
XStrsch 
structure, 6-1 through 6-2 
tokens, see XStrsep 
XString__intro, 6-1 
XStrlen, 6-9 
XStrlexcmp, 6-10 
XStrchr, 6-12 
XStrncasecmp, 6-6 
XStrncaselexcmp, 6-10 
XStrncat, 6-5 
XStrncmp, 6-6 
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XStrncpy, 6-8 
XStrnlexcmp, 6-10 
XStrpbrk, 6-12 
XStrrchr, 6-12 
XStrsch, 6-13 
XStrsep, 6-14 
XStrfromASC, 6-15 
XStrtoASC, 6-15 
XStrfromXCC8, 6-16 
XStrtoxCC8, 6-16 
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Customer Comments 


XEROX: 


VP Series Reference Library 
Document Interfaces Toolkit Software Reference 


Our goal is to improve the organization, ease of use, and accuracy of this library. Your comments 
and suggestions will help us tailor our manuals to better suit your needs. 


Company: 
City: 


Zip: 





Please rate the following: 


Excellent Good Fair Poor 
1. Is the organization suitable for your needs? O Oo O Oo 
2. Are you able to easily find the information you need? O | Oo O O 
3. Are the illustrations useful? Oo Oo Oo Oo 
4. Overall, how would you rate the documentation? O Oo O Oo 


Did you find any errors? 
Page number / Error 


How can we improve the documentation? 


| We appreciate your comments regarding our documentation. Thank you for taking the time to reply. 
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